Merge pull request #215 from nikomatsakis/team-functioning

proposal for how the team operates

crates/rust-project-goals-cli/src/rfc.rs

@@ -61,7 +61,7 @@ pub fn generate_comment(path: &Path) -> anyhow::Result<()> {
         }
 
         for member in members {
-            println!("* [ ] @{} (optional)", member.github);
+            println!("* [ ] {} (optional)", member.github);
         }
     }
 

src/SUMMARY.md

@@ -35,12 +35,20 @@
 
 * [The goals team](./admin/team.md)
 * [Running the program](./admin/running-the-program.md)
-    * [Sample: Call for Proposal blog post](./admin/samples/cfp.md)
-    * [Sample: Text for the main README](./admin/samples/main-readme.md)
-    * [Sample: Starting RFC text](./admin/samples/rfc.md)    
-    * [Sample: Goals page](./admin/samples/goals.md)    
-* [Overall setup](./admin/setup.md)
-* [Mdbook plugin details](./admin/mdbook_plugin.md)
-* [Commands you can run](./admin/commands.md)
-    * [`issues`, creating tracking issues](./admin/issues.md)
-    * [`updates`, create monthly blog post summary](./admin/updates.md) 
+    * [Team coordination](./admin/coordination.md)
+    * [Call for proposals](./admin/cfp.md)
+    * [Preparing the RFC](./admin/prepare_rfc.md)
+    * [Authoring monthly updates](./admin/author_updates.md)
+    * [Sample texts](./admin/samples.md)
+        * [Sample: Call for Proposal blog post](./admin/samples/cfp.md)
+        * [Sample: Text for the main README](./admin/samples/main-readme.md)
+        * [Sample: Starting RFC text](./admin/samples/rfc.md)    
+        * [Sample: Goals page](./admin/samples/goals.md)    
+* [Technical reference](./admin/reference.md)
+    * [Overall setup](./admin/setup.md)
+    * [Mdbook plugin details](./admin/mdbook_plugin.md)
+    * [`cargo rpg` command reference](./admin/commands.md)
+        * [`rfc`, export RFC text](./admin/rfc_command.md)
+        * [`fcp`, create the FCP merge comment](./admin/fcp_command.md)
+        * [`issues`, creating tracking issues](./admin/issues.md)
+        * [`updates`, create monthly blog post summary](./admin/updates.md) 

src/admin/author_updates.md

@@ -0,0 +1,27 @@
+# Author updates
+
+## Soliciting updates
+
+Triagebot can ping project-goal owners for updates. To use it, go to Zulip and execute a command like this.
+
+```
+@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". 
+
+The second string ("Oct-21") is the deadline for updates to be included.
+
+We need to improve this UI.
+
+## Drafting the post
+
+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.
+
+```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/cfp.md

@@ -0,0 +1,37 @@
+# Call for proposals
+
+Each goal milestone corresponds to six months, designated in the format YYYYhN, e.g., 2024h2 or 2025h1. To launch a new goal season, you should get started a couple of months before the new season starts:
+
+* For an H1 season, start around mid October of the year before.
+* For an H2 season, start around mid April of the year before.
+
+This is the checklist of steps to starting accepting goal proposals:
+
+* [ ] Prepare a Call For Proposals blog post on the [Inside Rust] blog based on [this sample](./samples/cfp.md).
+    * We use Inside Rust and not the Main blog because the target audience is would-be Rust contributors and maintainers.
+* [ ] Update the [main README page](../README.md) to indicate that the next round of goals is begin accepted.
+    * [Sample text to include.](./samples/main-readme.md)
+* [ ] Create a new directory `src/YYYYhN`, e.g., `src/2025h1`, with the following files. Note that the sample files below include `<!-- XXX -->` directives that are detected by the [mdbook plugin](./mdbook_plugin.md) and replaced with appropriate content automatically.
+    * A `src/YYYYhN/README.md` file that contains the draft RFC.
+        * [You can start with this sample file.](./samples/rfc.md)
+    * A `src/YYYYhN/goals.md` file containing the draft goal listing.
+        * [You can start with this sample file.](./samples/goals.md)
+    * A `src/YYYYhN/not_accepted.md` file containing the list of goals that were not accepted.
+        * [You can start with this sample file.](./samples/not_accepted.md)
+* [ ] Modify SUMMARY.md to include your new milestone with some text like what is shown below.
+
+Sample `SUMMARY.md` comments from 2025H1:
+
+```
+# ⏳ 2025H1 goal process
+
+- [Overview](./2025h1/README.md)
+- [Proposed goals](./2025h1/goals.md)
+- [Goals not accepted](./2025h1/not_accepted.md)
+```
+
+[Inside Rust]: https://blog.rust-lang.org/inside-rust/
+
+## Receiving PRs
+
+*to be written*

src/admin/commands.md

@@ -1,3 +1,3 @@
 # Commands
 
-There is a CLI for manipulating and checking project goals. You can run it with `cargo rpg` and it has a number of useful commands, described in this section. Use `cargo rpg --help` to get a summary.
+The `cargo rpg` command is a CLI for manipulating and checking project goals. This section provides a reference describing (some of) the ability commands. You can also try `cargo rpg --help` to get a summary.

src/admin/coordination.md

@@ -0,0 +1,25 @@
+# Team coordination
+
+## Discussion channels
+
+The [project-goals channel][pg] on Zulip is used for discussing the "meat" of project goals: e.g., updates, proposed goals, etc.
+
+[pg]: https://rust-lang.zulipchat.com/#narrow/channel/435869-project-goals
+
+The [project-goals/meta channel][pgm] on Zulip is used for meta discussions about running the program itself rest.
+
+[pgm]: https://rust-lang.zulipchat.com/#narrow/channel/478266-project-goals.2Fmeta
+
+To broadcast updates about the status of the goal program, we create a goal in every goal program correpsonding to running the program. Updates posted on that tracking issue will be posted in `project-goals`.
+
+## Meetings
+
+We do not currently have a regularly scheduled meeting. Sync meetings are coordinated ad-hoc and typically take place on Zulip in the [project-goals/meta channel][pgm].
+
+## Tracking our work
+
+To track work items, we use [issues tagged with the `meta` label](https://github.com/rust-lang/rust-project-goals/issues?q=is%3Aissue%20state%3Aopen%20label%3Ameta) on the [rust-lang/rust-project-goals](https://github.com/rust-lang/rust-project-goals/) repository.
+
+Issues [tagged with "help wanted"](https://github.com/rust-lang/rust-project-goals/issues?q=state%3Aopen%20label%3A%22help%20wanted%22) indicates places where we would like somebody to jump in. **Every such issue will also be tagged with mentoring instructions giving some idea how to get started.**
+
+There are also "meta" milestones for each program period to track specific goals related to that period.

src/admin/fcp_command.md

@@ -0,0 +1,13 @@
+# `fcp`, create the FCP merge comment
+
+The `cargo rpg fcp` command creates an FCP comment, since the format for the project goals RFC is distinct from other RFCs. 
+
+To use, simply invoke the command with the directory for the goal period, e.g., something like this:
+
+```
+> cargo rpg rfc src/2025h1
+```
+
+This will emit a comment to stdout that includes the name of each team which has registered asks along with checkboxes for each individual on that team.
+
+To avoid exceeding Github's limit of 50 usernames per message, only leads are cited with `@` usernames.

src/admin/prepare_rfc.md

@@ -0,0 +1,24 @@
+# Preparing the RFC
+
+## Review with teams
+
+Before opening the RFC it is best to review its current state with teams that have large number of goals. You want there to be as little surprise as possible once the RFC itself is opened, as it will be more annoying to make changes.
+
+Encourage teams to read over the list of asks assigned to them and answer questions like
+
+* Are there any goals that you are not aligned with? (i.e., work that you do not think should happen, or do not think should happen now)
+* Is there important work not represented here? Should that work have a project goal?
+* Is the team capable of following through on the total asks, or will that exceed team capacity?
+* If [flagship goals](../about/flagship_goals.md) have been decided, are there any concerns with those goals? Any suggestions for changes or alternatives?
+
+## Select flagship goals
+
+[Flagship goals](../about/flagship_goals.md) represent the 2-3 items that will be highlighted and will be the focus of external communication. The project goal team is responsible for selecting flagship goals. The criteria for flagship goals is described in the [About page](../about//flagship_goals.md). Because flagship goals generally take longer than 6 months to complete, most flagship goals are continuations from previous sessions, but as those goals get closer to completion, it may be good to shift the messaging towards a fresh focus.
+
+## Creating the RFC
+
+Run [`cargo rpg rfc`](./rfc_command.md) to export the RFC text in a format suitable for adding into the RFCs repository.
+
+## Beginning Final Comment Period
+
+Unlike ordinary RFCs, project goal RFCs are not chosen by any one team. Instead we craft a comment with the names of all project members. The leads of each team at minimum are required to check their box, though obviously the more boxes the better. You can craft this comment with the [`cargo rpg fcp`](./fcp_command.md) command.

src/admin/reference.md

@@ -0,0 +1,2 @@
+# Technical reference
+

src/admin/rfc_command.md

@@ -0,0 +1,11 @@
+# `rfc`, export RFC text
+
+The `cargo rpg rfc` command exports RFC text suitable for inclusion in the rust-lang/rfcs repository. It is intended for use when [preparing the RFC](./prepare_rfc.md) at the start of a goal period.
+
+To use, simply invoke the command with the directory for the goal period, e.g., something like this:
+
+```
+> cargo rpg rfc src/2025h1
+```
+
+This will read the README.md file and dump a version to stdout that can be copy-and-paste. This version will have URLs adjusted to point at the rust-lang/rust-project-goals repository and other cosmetic changes.

src/admin/running-the-program.md

@@ -1,69 +1,35 @@
 # Running the program
 
-So... somebody suckered you into serving as the owner of the goals program. Congratulations!
-This page will walk you through the process.
+Thank you for helping to run the goals program. Congratulations!
+This page will walk you through what is involved at each step of the the process.
 
-## Call for proposals
+## Calendar
 
-Each goal milestone corresponds to six months, designated in the format YYYYHN, e.g., 2024H2 or 2025H1.
-To launch a new goal season, you should get started a month or two before the new season starts:
+This section summarizes the dates involved with a theoretical program taking place in the year 2222.
+Each item has a link to more instructions.
 
-* For an H1 season, start around mid Oct or November of the year before.
-* For an H2 season, start around mid April or May of the year before.
+Each of the calendars has someoverlap with the previous and next previous.
 
-This is the checklist of steps to starting accepting goal proposals:
+### H1 calendar
 
-* [ ] Prepare a Call For Proposals blog post on the [Inside Rust] blog based on [this sample](./samples/cfp.md).
-    * We use Inside Rust and not the Main blog because the target audience is would-be Rust contributors and maintainers.
-* [ ] Update the [main README page](../README.md) to indicate that the next round of goals is begin accepted.
-    * [Sample text to include.](./samples/main-readme.md)
-* [ ] Create a new directory `src/YYYYhN`, e.g., `src/2025h1`, with the following files. Note that the sample files below include `<!-- XXX -->` directives that are detected by the [mdbook plugin](./mdbook_plugin.md) and replaced with appropriate content automatically.
-    * A `src/YYYYhN/README.md` file that contains the draft RFC.
-        * [You can start with this sample file.](./samples/rfc.md)
-    * A `src/YYYYhN/goals.md` file containing the draft goal listing.
-        * [You can start with this sample file.](./samples/goals.md)
-    * A `src/YYYYhN/not_accepted.md` file containing the list of goals that were not accepted.
-        * [You can start with this sample file.](./samples/not_accepted.md)
-* [ ] Modify SUMMARY.md to include your new milestone with some text like what is shown below.
+| Task      | *Nov–Dec <br> (prev. H2)* | Jan | Feb–Jun         | *Jul <br> (next H2*) |
+|-----------|---------------------------|-----|-----------------|----------------------|
+| [CFP]     | ██████                    | ░░░ |                 |                      |
+| [RFC]     |                           | ███ |                 |                      |
+| [Updates] |                           |     | ███████████████ |                      |
+| [Retro]   |                           |     |                 | ███                  |
 
-Sample `SUMMARY.md` comments from 2025H1:
+### H2 calendar
 
-```
-# ⏳ 2025H1 goal process
-
-- [Overview](./2025h1/README.md)
-- [Proposed goals](./2025h1/goals.md)
-- [Goals not accepted](./2025h1/not_accepted.md)
-```
-
-[Inside Rust]: https://blog.rust-lang.org/inside-rust/
-
-## Receiving PRs
-
-*to be written*
-
-## Preparing the RFC
-
-*to be written*
-
-## Opening the RFC
-
-*to be written*
-
-## Once the RFC is accepted
-
-*to be written*
-
-## Running the goal season
-
-* Every Monday go to Zulip and run:
-    * `@triagebot ping-goals 14 Oct-21`
-* To prepare the monthly blog post:
-    * Run [the `cargo run -- updates` command](./updates.md)
-    * Create a new post in main Rust blog found at [the blog.rust-lang.org repository](https://github.com/rust-lang/blog.rust-lang.org).
-
-
-
-## Finalizing the goal season
+| Task      | *May–Jun <br> (prev. H1)* | Jul | Aug–Dec         | *Jan <br> (next H1)* |
+|-----------|---------------------------|-----|-----------------|----------------------|
+| [CFP]     | ██████                    | ░░░ |                 |                      |
+| [RFC]     |                           | ███ |                 |                      |
+| [Updates] |                           |     | ███████████████ |                      |
+| [Retro]   |                           |     |                 | ███                  |
 
 
+[CFP]: ./cfp.md
+[RFC]: ./prepare_rfc.md
+[Updates]: ./author_updates.md
+[Retro]: ./retro.md

src/admin/samples.md

@@ -0,0 +1 @@
+# Sample texts