From 7a6060d3919903e35846eb0f0888c0a0a08d2dc9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Le=C3=B3n=20Orell=20Valerian=20Liehr?= <me@fmease.dev>
Date: Tue, 26 Aug 2025 17:10:15 +0200
Subject: [PATCH] [WIP] Tweak T-rustdoc processes docs

---
 src/SUMMARY.md                             |  1 +
 src/rustdoc/index.md                       | 10 ++++
 src/rustdoc/membership.md                  |  9 +++-
 src/rustdoc/proposals-and-stabilization.md | 63 +++++++++++++++-------
 src/rustdoc/repositories.md                | 19 +++++++
 5 files changed, 81 insertions(+), 21 deletions(-)
 create mode 100644 src/rustdoc/repositories.md

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index 1f5df0ec..5be550b6 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -80,6 +80,7 @@
     - [Calendar](./rustdoc/calendar.md)
     - [Meetings](./rustdoc/meetings.md)
     - [Membership](./rustdoc/membership.md)
+    - [Repositories](./rustdoc/repositories.md)
     - [Resources](./rustdoc/resources.md)
     - [Review Policy](./rustdoc/reviews.md)
     - [Proposals, Approval and Stabilization](./rustdoc/proposals-and-stabilization.md)
diff --git a/src/rustdoc/index.md b/src/rustdoc/index.md
index e8ceb108..bab8b41d 100644
--- a/src/rustdoc/index.md
+++ b/src/rustdoc/index.md
@@ -12,9 +12,19 @@ you're looking for the [rustc-dev-guide](https://rustc-dev-guide.rust-lang.org/r
   - *What meetings do the rustdoc team run and how can I attend?*
 - [Membership](./membership.md)
   - *What is expected of rustdoc team members and how do I join?*
+- [Repositories we maintain](./repositories.md)
+  - *Various code repositories the team maintains and contributes to*
 - [Resources](./resources.md)
   - *What useful resources are available for contributors and team members?*
 - [Review Policy](./reviews.md)
   - *How do I make a contribution which is easy to review? How do I start reviewing as a team member?*
 - [Proposals, Approval and Stabilization](./proposals-and-stabilization.md)
   - *How do I propose a change to the rustdoc team? What approval is necessary for my change?*
+
+<!-- FIXME(fmease): Specify backport and prioritization processes! -->
+
+<!-- FIXME(fmease): Somewhere I want to mention "cross-team purview"
+I.e., the fact that T-rustdoc members are allowed to modify T-libs*-owned `library/` if necessitated,
+similarly `compiler/` (but for compiler it's good to also assign a compiler team member).
+Similarly non-T-rustdoc may approve changes to `src/librustdoc/` if e.g. compiler modifs necessitate it
+-->
diff --git a/src/rustdoc/membership.md b/src/rustdoc/membership.md
index 4e693328..c6cdcd76 100644
--- a/src/rustdoc/membership.md
+++ b/src/rustdoc/membership.md
@@ -28,6 +28,7 @@ is ready when they have demonstrated three things:
 [CoC]: https://www.rust-lang.org/policies/code-of-conduct
 
 Being promoted to member implies a number of privileges:
+<!-- FIXME(fmease): Not only r+ but also GH approval/merge rights in certain other repos -->
 
 - Members have `r+` (approve a pull request) privileges and can do reviews (they are expected to
   use those powers appropriately, as discussed previously). They also have access to control
@@ -98,12 +99,18 @@ extended.
 If the invitation is accepted by the individual, the rustdoc team leads will update the [team]
 repository to reflect their new role.
 
+<!-- FIXME(fmease): Need to be manually added to private rustdoc team channel because it's
+not tracked by sync-team at the time of writing -->
+
 ## Alumni status
 If at any time a rustdoc team member wishes to take a break from participating, they can opt to put
 themselves into alumni status. When in alumni status, they will be removed from
 GitHub aliases and the like, so that they need not be bothered with pings and messages. They will
 also not have r+ privileges. **Alumni members will however still remain members of the GitHub
-org overall.**
+org overall.** <!-- FIXME(fmease): No longer accurate! -->
+
+<!-- FIXME(fmease): Need to be manually removed from private rustdoc team channel because it's
+not tracked by sync-team at the time of writing -->
 
 People in alumni status can ask to return to "active" status at any time. This request would
 ordinarily be granted automatically barring extraordinary circumstances.
diff --git a/src/rustdoc/proposals-and-stabilization.md b/src/rustdoc/proposals-and-stabilization.md
index 8a9910e0..46c6b4f1 100644
--- a/src/rustdoc/proposals-and-stabilization.md
+++ b/src/rustdoc/proposals-and-stabilization.md
@@ -4,42 +4,59 @@ for permission to proceed with an experiment or refactoring, or when stabilizing
 document aims to summarise the various processes that the rustdoc team has for making approval
 decisions and when each should be used.
 
-## Approvals
-There are two mechanisms that the team can use to approve a proposal (not all approval mechanisms
-are suitable for each method of making a proposal - see below):
 
-- r+
-  - A proposal (an RFC or an FCP) is r+'d when it is approved to be merged.
-  - r+ can only be used to approve a PR.
-- FCP
-  - A final comment period will require sign-off from a majority (all members minus 2)
-    of the rustdoc team to approve a proposal and then a ten day waiting period.
-  - FCPs can be used to approve any form of proposal.
+[*r+*]: ../compiler/reviews.html#bors
 
 ## Proposals
-There are three ways to propose a change to the rustdoc team. The appropriate choice depends on
+There are four ways to propose a change to the rustdoc team. The appropriate choice depends on
 the nature of the proposal, described below.
 
-- Open a discussion on the [rustdoc zulip thread].
-  - This is the preferred way. It allows to prevent users to lose too much time implementing
+- Open a discussion in the [rustdoc Zulip channel].
+  - This is the preferred way <!-- FIXME(fmease): not always tho? Just open a PR dude -->.
+    It allows to prevent users to lose too much time implementing
     something if in the end, the team will ask major changes or even refuse it. After the
     discussion, if accepted and depending on the change, an RFC or a PR will be the next step.
+  - <!-- FIXME(fmease): Clarify what "approval" means. Namely the approvals are casual,
+    "non-binding". >=1 endorsements is fine/usual -->
 - Request For Comments (RFC)
-  - RFCs are pull requests to the [`rust-lang/rfcs`][rfcs] repository and are a heavy-weight
+  - RFCs are pull requests to the [`rust-lang/rfcs`] repository and are a heavy-weight
     proposal mechanism, reserved for significant changes.
   - RFC proposals can only be approved by *FCPs*.
+  - <!-- FIXME(fmease): Or mention the "r+ after FCP" topic from above here instead -->
 - Pull Request (PR)
-  - Opening a pull request on the [`rust-lang/rust`][rust] repository is a lightweight
+  - Opening a pull request on the [`rust-lang/rust`] repository is a lightweight
     mechanism suitable for most proposals. This is preferred in cases such as stabilization
     of a rustdoc flag or addition of a new target.
   - PR proposals can be approved by *FCPs* or *r+*. See *When are FCPs/RFCs required?*
     section below when *r+* isn't sufficient alone.
 - Issues
-  - Opening an issue on the [`rust-lang/rust`][rust] repository are also a good starting
+  - Opening an issue in the [`rust-lang/rust`] repository is also a good starting
     point if you don't know which of the previous ways is the best fit.
+  - <!-- FIXME(fmease): Clarify that there's no process for approvals for
+    GH issues; moreover mention that we usually don't FCP issue proposals but
+    instead the corresponding PR -->
+
+[rustdoc Zulip channel]: https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc
+[`rust-lang/rust`]: https://github.com/rust-lang/rust
+[`rust-lang/rfcs`]: https://github.com/rust-lang/rfcs
 
-[rustdoc zulip thread]: https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc
-[rust]: https://github.com/rust-lang/rust
+## Approvals
+There are two mechanisms that the team can use to approve a [proposal](#proposals). (not all approval mechanisms
+are suitable for each method of making a proposal -- [see below](#proposals)):
+
+- [*r+*] <!-- or GH approval or merge -->
+  - A proposal is *r+*'d when it is approved to be merged.
+  - *r+* can only be used to approve a PR.
+  - <!-- FIXME(fmease): *somewhere* I want to clarify *who* is in charge of the r+
+    (namely any team member(s) but usually PR assignee(s)) -->
+  - <!-- FIXME(fmease): r-l/r isn't the only repo (e.g., dev guide, forge, rustdoc-json-types, rfcs) -->
+- FCP
+  - A final comment period will require sign-off from a majority (all members minus 2)
+    of the rustdoc team to approve a proposal and then a ten day waiting period.
+  - FCPs can be used to approve any form of proposal.
+  - <!-- FIXME(fmease): Somewhere I want to clarify that after an FCP, in r-l/r
+    a separate r+ is still necessary by someone / a GH approval in other repos;
+    also I want to mention somewhere that any team is allowed to merge an FCP'ed RFC -->
 
 ### When are FCPs/RFCs required?
 
@@ -48,6 +65,9 @@ the GUI web interface, new command-line arguments, new attributes, etc. However,
 is considered too big/important, an RFC will need to be written and approved before the change
 will be accepted.
 
+<!-- FIXME(fmease): ^^^ Tweak phrasing. The stabilization of an already-RFC'ed feature
+always(?) requires an FCP (and doesn't need another RFC :P) -->
+
 When starting an FCP, make sure only the relevant subteam is labeled on the issue/PR, to avoid
 pinging people with changes they aren't interested in.
 
@@ -56,11 +76,15 @@ If the approval required for the contribution requires an RFC, then the contribu
 should be closed or marked as blocked, with a request to create an RFC first. If approval of
 a PR is acceptable for the specific contribution (see below), then the approval process can begin.
 
-### Can I work on code experimentally before a approval is gained?
+<!-- FIXME: Mention S-blocked -->
+
+### Can I work on code experimentally before an approval is gained?
 Of course! You are free to work on PRs or write code. But those PRs should be marked as
 experimental and they should not land, nor should anyone be expected to review them (unless
 folks want to).
 
+<!-- FIXME: Mention S-experimental -->
+
 ## What makes a good proposal?
 A good proposal will address the following:
 
@@ -74,7 +98,6 @@ A good proposal will address the following:
 * **Alternatives, concerns, and key decisions:** Were there any alternatives considered? If so, why
   did you pick this design?
 
-[rfcs]: https://github.com/rust-lang/rfcs
 [Haddock]: https://haskell-haddock.readthedocs.io/latest/
 [Wikipedia]: https://www.wikipedia.org/
 [Racket]: https://docs.racket-lang.org/
diff --git a/src/rustdoc/repositories.md b/src/rustdoc/repositories.md
new file mode 100644
index 00000000..3e842fe6
--- /dev/null
+++ b/src/rustdoc/repositories.md
@@ -0,0 +1,19 @@
+# Repositories maintained by the Rustdoc Team
+
+<!-- FIXME(fmease): Polish this -->
+
+While the [rust-lang/rust] repository has the majority of the code for the rustdoc tool, there are a handful of additional repositories with other crates/dependencies that the rustdoc team are responsible for:
+
+To ensure that the team is able to respond to urgent issues that originate in any of these repositories, all members of the rustdoc team have access to create and merge pull requests. However, each repository typically has team members who are the most familiar with the repository and act as its primary maintainers.
+
+- The [`rustc` development guide][rustc-dev-guide], the entrypoint documentation for those interested in hacking the compiler. <!-- FIXME(fmease): Tweak wording (comaintained) -->
+- [rustdoc-types] <!-- FIXME(fmease): Description -->
+- Forge <!-- FIXME(fmease): Description (comaintained) -->
+
+You can see the full list [here](https://github.com/orgs/rust-lang/teams/rustdoc/repositories).
+
+If you want to start (or are already) contributing to the Rust project and you have expertise or interest in any of these repositories, feel free to get in touch!
+
+[rust-lang/rust]: https://github.com/rust-lang/rust
+[rustc-dev-guide]: https://github.com/rust-lang/rustc-dev-guide
+[rustdoc-types]: https://github.com/rust-lang/rustdoc-types/