Merge pull request #142 from nikomatsakis/see-also

Whooops... "see also" for real

Author: nikomatsakis

mdbook-goals/src/gh/issues.rs

@@ -122,6 +122,7 @@ pub fn fetch_issue(repository: &Repository, issue: u64) -> anyhow::Result<Existi
     let output = Command::new("gh")
         .arg("-R")
         .arg(&repository.to_string())
+        .arg("issue")
         .arg("view")
         .arg(&format!("{issue}"))
         .arg("--json")

mdbook-goals/src/json.rs

@@ -150,8 +150,13 @@ fn checkboxes(issue: &ExistingGithubIssue) -> anyhow::Result<Progress> {
             let issue_urls = c["issues"].split(&[',', ' ']).filter(|s| !s.is_empty());
 
             for issue_url in issue_urls {
-                let Some(c) = re::SEE_ALSO_ISSUE.captures(issue_url) else {
-                    anyhow::bail!("invalid issue URL `{issue_url}`")
+                let c = match (
+                    re::SEE_ALSO_ISSUE1.captures(issue_url),
+                    re::SEE_ALSO_ISSUE2.captures(issue_url),
+                ) {
+                    (Some(c), _) => c,
+                    (None, Some(c)) => c,
+                    (None, None) => anyhow::bail!("invalid issue URL `{issue_url}`"),
                 };
                 let repository = Repository::new(&c["org"], &c["repo"]);
                 let issue_number = c["issue"].parse::<u64>()?;

mdbook-goals/src/re.rs

@@ -41,9 +41,16 @@ lazy_static! {
 
 lazy_static! {
     pub static ref SEE_ALSO_QUERY: Regex =
-        Regex::new(r"^\| *See also *\| (?P<issues>[^, ]+,|[^, ] )+ *\| *$").unwrap();
+        Regex::new(r"^\| *See also *\|(?P<issues>[^|]+)\| *$").unwrap();
 }
 
 lazy_static! {
-    pub static ref SEE_ALSO_ISSUE: Regex = Regex::new(r"(?P<org>[^#/]*)/(?P<repo>[^#/]*)#(?P<issue>[0-9]+)|https://github.com/(?P<org>[^#/]*)/(?P<repo>[^#/]*)/issues/(?P<issue>[0-9]+)").unwrap();
+    pub static ref SEE_ALSO_ISSUE1: Regex =
+        Regex::new(r"(?P<org>[^#/]*)/(?P<repo>[^#/]*)#(?P<issue>[0-9]+)").unwrap();
+}
+
+lazy_static! {
+    pub static ref SEE_ALSO_ISSUE2: Regex =
+        Regex::new(r"https://github.com/(?P<org>[^#/]*)/(?P<repo>[^#/]*)/issues/(?P<issue>[0-9]+)")
+            .unwrap();
 }

src/SUMMARY.md

@@ -31,4 +31,5 @@
 
 * [Overall setup](./admin/setup.md)
 * [Mdbook plugin details](./admin/mdbook_plugin.md)
-* [Commands you can run](./admin/commands.md)
+* [Commands you can run](./admin/commands.md)
+    * [Creating tracking issues](./admin/issues.md)

src/admin/issues.md

@@ -0,0 +1,19 @@
+# Creating tracking issues
+
+Usage:
+
+```
+> cargo run -- issues
+```
+
+The `issues` command is used to create tracking issues at the start of a project goal session. When you first run it, it will simply tell you what actions it plans to take.
+
+To actually commit and create the issues, supply the `--commit` flag:
+
+```
+> cargo run -- issues --commit
+```
+
+This will also edit the goal documents to include a link to each created tracking issue. You should commit those edits.
+
+You can later re-run the command and it will not repeat actions it has already taken.c

src/how_to/report_status.md

@@ -1,74 +1,76 @@
 # Report status
 
-Every accepted project goal has an associated tracking issue.
+Every accepted project goal has an associated tracking issue. These are created [automatically by the project-goals admin tool](../admin/issues.md). Your job as a project goal owner is to provide regular status updates in the form of a comment indicating how things are going. These will be collected into regular blog posts on the Rust blog as well as being promoted in other channels.
 
-Owners are expected to provide regular status updates in the form of a comment indicating how things are going.
+## Updating the progress bar
 
-## Documenting your plan and your progress
-
-To help users
+When we display the status of goals, we include a progress bar based on your documented plan. We recommend you keep this up to date. You can mix and match any of the following ways to list steps.
 
 ### Checkboxes
 
-The deafult
-
-### Search queries
+The first option is to add checkboxes into the top comment on the tracking issue. Simply add boxes like `* [ ]` or `* [x]` for a completed item. The tool will count the number of checkboxes and use that to reflect progress. Your tracking issue will be pre-propulated with checkboxes based on the goal doc, but feel free to edit them.
 
-## Status updates are reported out
+Best practice is to start with a high level list of tasks:
 
-The status updates from the tracking issues are used to author a blog post for Inside Rust on a monthly basis.
-If status updates are missing, the blog post will indicate that there is no status update.
-This will also prompt the project to reach out and check on the progress of the goal.
-If goal progress is slow for some reason -- maybe life intervened and you were not able to work on the goal --
-it is much better to leave a status report to that effect than to say nothing at all.
+```
+* [ ] Author code
+* [ ] Author RFC
+* [ ] Accept RFC
+* [ ] Test
+* [ ] Stabilize
+```
 
-## Goals without updates can be paused
+each time you provide a status update, check off the items that are done, and add new items with more detailed to-do items that represent your next steps.
 
-If goals do not receive updates for an extended period of time, they may be marked as **paused**.
-That's not meant as a judgment: things happen. It's just an indicator of the status.
-You can also resume work again!
+### Search queries
 
-## Bot interactions
+For larger project goals, it can be more convenient to track progress via github issues. You can do that by removing all the checkboxes from your issue and instead adding a "Tracked issues" line into the metadata table on your tracking issue. It should look like this:
 
-**Status:** Halluncinated. We need to author this code.
+```
+| Metadata      | |
+| --------      | --- |
+| Owner(s)      | ... |
+| Team(s)       | ... |
+| Goal document | ... |
+| Tracked issues | [rust-lang/rust label:A-edition-2024 label:C-tracking-issue -label:t-libs](...) |
+```
 
-To aid in this process, the Rust triagebot will ping owners around the end of the month.
-Pings will be placed as a comment on the tracking issue.
-Owners should leave a comment in response; the bot will then hide its comment to avoid clutter.
+The first 3 lines should already exist. The last line is the one you have to add. The "value" column should have a markdown link, the contents of which begin with a repo name and then search parameters in Github's format. The tool will conduct the search and count the number of open vs closed issues. The `(...)` part of the link should be to github so that users can click to do the search on their own.
 
-## How to write a status update
+You can find an example on the [Rust 2024 Edition tracking issue](https://github.com/rust-lang/rust-project-goals/issues/117).
 
-Status updates should be written for general Rust contributors.
-They will be posted to the [Inside Rust](https://blog.rust-lang.org/inside-rust/)
-Status updates should include the following information:
+### Use "See also" to refer to other tracking issues
 
-* What happened since the last update
-    * Key decisions made
-    * Milestones achieved
-* Current plans
-    * What is the milestone you are working towards
-    * What is happening right now?
-* Help wanted (if any)
-    * Status updates are a great place to highlight requests for help or contribution
+If you already have a tracking issue elsewhere, just add a "See also" line into your metadata. The value should be a comma-or-space-separated list of URLs or `org/repo#issue` github references:
 
-## Status update template
+```
+| Metadata      | |
+| --------      | --- |
+| Owner(s)      | ... |
+| Team(s)       | ... |
+| Goal document | ... |
+| See also | rust-lang/rust#123 |
+```
 
-Here is a template you can use
+We will recursively open up the "see also" issue and extract checkboxes (or search queries / see-also tags) from there.
 
-```
-### Since the last update...
+### Binary issues
 
-*Describe any key decisions or events since the last update.*
+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.
 
-### Up next
+## Status update comments
 
-*Describe the next milestone you are working towards.*
+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. 
 
-### Help wanted
+There is no strict format for these updates but we recommend including the following information:
 
-*Describe ways that contributors can help (if any, feel free to delete if contribution is not needed.)*
+* 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? 
 
-*Ideal here is to link to an issue with contribution instructions.*
-```
+## Closing the issue
 
+Closing the tracking issue is a signal that you are no longer working on it. This can be because you've achieved your goal or because you have decided to focus on other things. Also, tracking issues will automatically be closed at the end of the project goal period.
 
+When you close an issue, the state of your [checkboxes](#checkboxes) makes a difference. If they are 100% finished, the goal will be listed as completed. If there are unchecked items, the assumption is that the goal is only partly done, and it will be listed as unfinished. So make sure to check the boxes if the goal is done!