document new procedure

Author: Niko Matsakis

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.