Merge pull request #299 from nikomatsakis/why-this-goal-help-wanted

include 'help wanted" and "tl;ldr" comments

Author: lqd

crates/rust-project-goals-cli-llm/src/templates.rs

@@ -73,6 +73,13 @@ pub struct UpdatesGoal {
     /// True if the issue is closed.
     pub is_closed: bool,
 
+    /// True if there are "help wanted" comments OR the TL;DR includes a help wanted request.
+    pub has_help_wanted: bool,
+
+    /// If there are comments that include ["help wanted"](`rust_project_goals::re::HELP_WANTED`)
+    /// comments, those comments are included here.
+    pub help_wanted: Vec<HelpWanted>,
+
     /// Markdown with update text (bullet list)
     pub comments: Vec<ExistingGithubComment>,
 
@@ -81,4 +88,15 @@ pub struct UpdatesGoal {
 
     /// Progress towards the goal
     pub progress: Progress,
+
+    /// TL;DR comment (if any, empty string if none)
+    pub tldr: Option<String>,
+
+    /// Contents of a "Why this goal?" section in the tracking issue (empty string if not present)
+    pub why_this_goal: String,
+}
+
+#[derive(Serialize, Debug)]
+pub struct HelpWanted {
+    pub text: String,
 }

crates/rust-project-goals-cli-llm/src/updates.rs

@@ -1,12 +1,14 @@
 use anyhow::Context;
 use chrono::{Datelike, NaiveDate};
+use rust_project_goals::markwaydown;
+use rust_project_goals::re::{HELP_WANTED, TLDR};
 use rust_project_goals::util::comma;
 use rust_project_goals_json::GithubIssueState;
 use std::io::Write;
 use std::path::Path;
 use std::process::{Command, Stdio};
 
-use crate::templates::{self, Updates, UpdatesGoal};
+use crate::templates::{self, HelpWanted, Updates, UpdatesGoal};
 use rust_project_goals::gh::issues::ExistingGithubIssue;
 use rust_project_goals::gh::{
     issue_id::{IssueId, Repository},
@@ -92,6 +94,11 @@ async fn prepare_goals(
             continue;
         }
 
+        let issue_id = IssueId {
+            repository: repository.clone(),
+            number: issue.number,
+        };
+
         let title = &issue.title;
 
         progress_bar::print_progress_bar_info(
@@ -107,26 +114,99 @@ async fn prepare_goals(
         comments.sort_by_key(|c| c.created_at.clone());
         comments.retain(|c| !c.is_automated_comment() && filter.matches(c));
 
+        let tldr = tldr(&issue_id, &mut comments)?;
+
+        let (has_help_wanted, help_wanted) = help_wanted(&issue_id, &tldr, &comments)?;
+
+        let why_this_goal = why_this_goal(&issue_id, issue)?;
+
         result.push(UpdatesGoal {
             title: title.clone(),
             issue_number: issue.number,
             issue_assignees: comma(&issue.assignees),
-            issue_url: IssueId {
-                repository: repository.clone(),
-                number: issue.number,
-            }
-            .url(),
+            issue_url: issue_id.url(),
             progress,
+            has_help_wanted,
+            help_wanted,
             is_closed: issue.state == GithubIssueState::Closed,
             num_comments: comments.len(),
             comments,
+            tldr,
+            why_this_goal,
         });
 
         progress_bar::inc_progress_bar();
     }
     Ok(result)
 }
 
+/// Search for a TL;DR comment. If one is found, remove it and return the text.
+fn tldr(
+    _issue_id: &IssueId,
+    comments: &mut Vec<ExistingGithubComment>,
+) -> anyhow::Result<Option<String>> {
+    let Some(index) = comments.iter().position(|c| c.body.starts_with(TLDR)) else {
+        return Ok(None);
+    };
+
+    let comment = comments.remove(index);
+    Ok(Some(comment.body[TLDR.len()..].trim().to_string()))
+}
+
+/// Search for comments that talk about help being wanted and extract that
+fn help_wanted(
+    _issue_id: &IssueId,
+    tldr: &Option<String>,
+    comments: &[ExistingGithubComment],
+) -> anyhow::Result<(bool, Vec<HelpWanted>)> {
+    use std::fmt::Write;
+
+    let mut help_wanted = vec![];
+
+    let tldr_has_help_wanted = tldr.as_deref().unwrap_or("").lines().any(|line| HELP_WANTED.is_match(line));
+
+    for comment in comments {
+        let mut lines = comment.body.split('\n').peekable();
+
+        // Look for a line that says "Help wanted" at the front.
+        // Then extract the rest of that line along with subsequent lines until we find a blank line.
+        while lines.peek().is_some() {
+            while let Some(line) = lines.next() {
+                if let Some(c) = HELP_WANTED.captures(line) {
+                    help_wanted.push(HelpWanted {
+                        text: c["text"].to_string()
+                });
+                    break;
+                }
+            }
+
+            while let Some(line) = lines.next() {
+                if line.trim().is_empty() {
+                    break;
+                } else {
+                    let last = help_wanted.len() - 1;
+                    writeln!(&mut help_wanted[last].text, "{line}")?;
+                }
+            }
+        }
+    }
+
+    Ok((tldr_has_help_wanted || !help_wanted.is_empty(), help_wanted))
+}
+
+fn why_this_goal(
+    issue_id: &IssueId,
+    issue: &ExistingGithubIssue,
+) -> anyhow::Result<String> {
+    let sections = markwaydown::parse_text(issue_id.url(), &issue.body)?;
+    for section in sections {
+        if section.title == "Why this goal?" {
+            return Ok(section.text.trim().to_string());
+        }
+    }
+    return Ok("".to_string());
+}
+
 struct Filter<'f> {
     start_date: NaiveDate,
     end_date: &'f Option<NaiveDate>,

crates/rust-project-goals/src/markwaydown.rs

@@ -31,8 +31,14 @@ pub struct Table {
     pub rows: Vec<Vec<String>>,
 }
 
-pub fn parse(path: &Path) -> anyhow::Result<Vec<Section>> {
+pub fn parse(path: impl AsRef<Path>) -> anyhow::Result<Vec<Section>> {
+    let path = path.as_ref();
     let text = std::fs::read_to_string(path)?;
+    parse_text(path, &text)
+}
+
+pub fn parse_text(path: impl AsRef<Path>, text: &str) -> anyhow::Result<Vec<Section>> {
+    let path: &Path = path.as_ref();
     let mut result = vec![];
     let mut open_section = None;
     let mut open_table = None;
@@ -54,11 +60,14 @@ pub fn parse(path: &Path) -> anyhow::Result<Vec<Section>> {
             }
             CategorizeLine::TableRow(mut row) => {
                 if open_section.is_none() {
-                    anyhow::bail!(
-                        "{}:{}: markdowwn table outside of any section",
-                        path.display(),
-                        line_num
-                    );
+                    // create an "anonymous" section to house the table
+                    open_section = Some(Section {
+                        line_num,
+                        level: 0,
+                        title: String::new(),
+                        text: String::new(),
+                        tables: vec![],
+                    });
                 }
 
                 if let Some(table) = &mut open_table {

crates/rust-project-goals/src/re.rs

@@ -100,3 +100,13 @@ pub fn is_just(re: &Regex, s: &str) -> bool {
     let output = re.replace(s, "X");
     output == "X"
 }
+
+lazy_static! {
+    /// If a line within a comment begins with this text, it will be considered a request for help
+    pub static ref HELP_WANTED: Regex =
+        Regex::new(r"^(?i:help wanted:|\*\*help wanted:\*\*) (?P<text>.*)")
+            .unwrap();
+}
+
+/// If a comment begins with this text, it will be considered a summary.
+pub const TLDR: &str = "TL;DR:";

src/admin/author_updates.md

@@ -2,10 +2,10 @@
 
 ## Soliciting updates
 
-Triagebot can ping project-goal owners for updates. To use it, go to Zulip and execute a command like this.
+Triagebot can ping project-goal owners for updates. To use it, go to Zulip and execute a command like this (you need to use an `@` in front of triagebot).
 
 ```
-@triagebot ping-goals 14 Oct-21
+triagebot ping-goals 14 Oct-21
 ```
 
 The first number (14) is a threshold, it is typically set to the current day of the month (e.g., the above command assumes it is Oct 14). It means "if they have posted a comment in the last 14 days, don't bug them". 
@@ -14,14 +14,15 @@ The second string ("Oct-21") is the deadline for updates to be included.
 
 We need to improve this UI.
 
-## Drafting the post
+## Filling out the template
 
-The [blog post template][updates template] includes a longer description of the flagship goals as well as a bullet-point or two for each of the other goals -- more than that and the blog post becomes overwhelming, the goal is mostly to let people find the goal they're interested in and click to read the full details. You can fill out the template by hand but you can also use the `cargo rpg updates` ([documented here](./updates.md)) to prepare a rough draft; the tool uses an LLM currently hosted on AWS Bedrock and hence requires setting up an AWS account.
+Run the `cargo rpg updates` command to create the blog post template. If running from within vscode, the `--vscode` command will open the result in a fresh tab, which is convenient.
+
+The template will be filled in with the list of flagship goals. Each flagship goal will have their [Why this goal?](./merge_rfc.md#author-the-why-this-goal-sections-for-the-flagship-goals) section auto-inserted from the corresponding tracking issue.
+
+The template will also include the detailed list of updates in a `<details>` section as well as any TL;DR comments left by users.
+
+The update template itself is maintained with handlebars, you will find it [here](https://github.com/rust-lang/rust-project-goals/blob/main/templates/updates.hbs).
 
-```bash
-> cargo rpg updates
-```
 
-Once the draft is prepared, create a hackmd in the rust-project-goals hackmd team, post it to `#project-goals` and apply edits (particularly for the flagship goals). Then open a PR against [the blog.rust-lang.org repository](https://github.com/rust-lang/blog.rust-lang.org).
 
-[updates template]: https://github.com/rust-lang/rust-project-goals/blob/main/templates/updates.hbs

src/admin/merge_rfc.md

@@ -1,13 +1,31 @@
 # Merging the RFC
 
-Once the RFC is accepted
-
-* Merge the RFC itself
-* Run `cargo rpg teams` to prepare adjustment to the teams repository
-    * In particular to populate the project-goal-owners team 
-    * This will be needed to allow people to author updates on their goals
-* Run `cargo rpg issues` to create and update tracking issues
-    * Continuing goals will be moved to the new milestone
-    * You can run this tool over and over to keep things synchronized
-* Close out of date issues
-    * For all issues in previous milestone, close them
+Once the RFC is accepted, you need to take the following steps.
+
+## Merge the RFC itself
+
+Update the RFC and merge as normal
+
+## Update the teams
+
+Run `cargo rpg teams` to prepare adjustment to the teams repository. You will need to have a checkout of the teams repository somewhere; you pass the command the path to that repo and it will make changes. You can then commit the changes and prepare a PR. 
+
+This will create a `project-goal-owners` team containing all the project goal owners. It will also add people to the rust-lang repository. This may trigger them to get invites if they are not already members of the org. You should encourage them to accept those invites. If they don't take these steps you won't be able to assign them to issues and they won't be able to author updates, etc.
+
+## Create the milestone
+
+Next you need to (manually) create a milestone on the rust-project-goals repository with the appropriate name (e.g., `2025h1`). We usually create a paired meta milestone like `2025h1-meta` to track other tasks related to running the program.
+
+## Create tracking issues
+
+Finally, you can create the tracking issues. To do this, you run `cargo rpg issues`. Before doing so, make sure that the metadata for any goals that are continuing from the previous milestone already lists the appropriate tracking issue, otherwise the comment will create a duplicate issue.
+
+You can run the command more than once, it tries to pick up from where it left off. It will adjust the state of all issues to match what is expected.
+
+## Author the "why this goal" sections for the flagship goals
+
+For each flagship goal, you should add a section entitled `## Why this goal?` into the tracking issue. Put in there about a paragraph of text that explains the background for this goal. This text will be included verbatim when you prepare monthly updates, so make it readily understood. Often this is the same text that appeared in the RFC itself.
+
+## Close old tracking issues
+
+Finally, you can go to the previous milestone, find all remaining issues, and close them. These should correspond to goals from the previous session that were not continued into the current one.

src/how_to/report_status.md

@@ -58,16 +58,23 @@ We will recursively open up the "see also" issue and extract checkboxes (or sear
 
 If we don't find any of the above, we will consider your issue either 0% done if it is not yet closed or 100% done if it is.
 
-## Status update comments
+## Status update comments and summaries
 
-Status updates are posted as comments on the Github tracking issue. You will receive regular pings on Zulip to author status updates periodically. It's a good idea to take the opportunity to update your [progress checkboxes](#checkboxes) as well. 
-
-There is no strict format for these updates but we recommend including the following information:
+We encourage you to post regular detailed updates about your progress as comments on the Github tracking issue. There is no strict format for these updates but we recommend including the following information:
 
 * What happened since the last update? Were any key decisions made or milestones achieved?
 * What is the next step to get done?
 * Are you blocked on anyone or anything?
-* Is there any opportunity to others to pitch in and help out? 
+
+Status update comments will be included verbatim in a "details" section of the monthly blog post.
+
+### Help wanted comments
+
+If your updates include the text `Help wanted:` or `**Help wanted:**` at the start of a line, then the remainder of that line (and any non-block lines afterwards) will be extracted as a "help wanted" request. This will be highlighted in the monthly blog post.
+
+### Summary comments
+
+Once per month, you will start receiving pings to author a monthly status update. This is a special update that will be included verbatim in the blog post. Unless you have a flagship goal, the monthly status update should be short, no more than 2 or 3 bullet points. For a flagship goal it can be longer. To write your monthly status update, leave a comment that begins with the text "TL;DR:". It's a good idea to take the opportunity to update your [progress checkboxes](#checkboxes) as well, as the status bar in the blog post will be based on those.
 
 ## Closing the issue
 

templates/updates.hbs

@@ -1,20 +1,58 @@
-The Rust project is currently working towards a [slate of 26 project
-goals](https://rust-lang.github.io/rust-project-goals/2024h2/goals.html), with 3 of them designed as [Flagship
-Goals](https://rust-lang.github.io/rust-project-goals/2024h2/goals.html#flagship-goals). This post provides selected
-updates on our progress towards these goals (or, in some cases, lack thereof). The full details for any particular goal
-are available in its associated [tracking issue on the rust-project-goals
-repository](https://github.com/rust-lang/rust-project-goals/milestone/2).
+The Rust project is currently working towards a [slate of 26 project goals](https://rust-lang.github.io/rust-project-goals/{{milestone}}/goals.html), with 3 of them designed as [Flagship Goals](https://rust-lang.github.io/rust-project-goals/{{milestone}}/goals.html#flagship-goals). This post provides selected updates on our progress towards these goals (or, in some cases, lack thereof). The full details for any particular goal are available in its associated [tracking issue on the rust-project-goals repository](https://github.com/rust-lang/rust-project-goals/issues?q=is%3Aissue%20state%3Aopen%20label%3AC-tracking-issue).
 
 ## Flagship goals
 
 {{#each flagship_goals}}
 {{>introduce_goal}}
+
+<!-- markdown separator --> 
+
+**Why this goal?** {{why_this_goal}}
+
+**What has happened?** {{{tldr}}}
+
+<!-- markdown separator --> 
+
+{{>goal_comments}}
+{{/each}}
+
+## Goals looking for help
+
+{{#each other_goals}}
+{{#if has_help_wanted}}
+{{>introduce_goal}}
+
+<!-- markdown separator --> 
+{{{tldr}}}
+<!-- markdown separator --> 
+
+{{#each help_wanted}}
+
+<!-- markdown separator --> 
+![Help wanted](https://img.shields.io/badge/Help%20wanted-yellow) {{{text}}}
+<!-- markdown separator --> 
+
+{{/each}}
+
+<!-- markdown separator --> 
+
 {{>goal_comments}}
+{{/if}}
 {{/each}}
 
-## Other goals
+## Other goal updates
 
 {{#each other_goals}}
+{{#if has_help_wanted}}
+{{else}}
 {{>introduce_goal}}
+
+<!-- markdown separator --> 
+
+{{{tldr}}}
+
+<!-- markdown separator --> 
+
 {{>goal_comments}}
+{{/if}}
 {{/each}}