Add rustdoc team processes #852

GuillaumeGomez · 2025-05-21T15:01:58Z

cc @rust-lang/rustdoc

Rendered

src/rustdoc/proposals-and-stabilization.md

src/rustdoc/resources.md

src/rustdoc/README.md

src/rustdoc/meetings.md

src/rustdoc/membership.md

ehuss · 2025-05-21T15:46:13Z

Can you also add the rustdoc team to triagebot.toml for this directory and give yourselves permissions in https://github.com/rust-lang/team/blob/HEAD/repos/rust-lang/rust-forge.toml?

src/rustdoc/proposals-and-stabilization.md

aDotInTheVoid

Thanks for working on this! I'm very happy to see this written down.

src/rustdoc/membership.md

src/rustdoc/README.md

src/rustdoc/proposals-and-stabilization.md

src/rustdoc/membership.md

fmease · 2025-05-21T17:34:34Z

(This PR will obviously need a T-rustdoc FCP to make it official once most things have been sufficiently fleshed out)

Manishearth

overall this seems pretty good!

GuillaumeGomez · 2025-05-21T18:54:42Z

(This PR will obviously need a T-rustdoc FCP to make it official once most things have been sufficiently fleshed out)

Absolutely!

GuillaumeGomez · 2025-05-21T18:57:52Z

I added the change in triagebot.toml as suggested by @ehuss.

I went through all comments.

@fmease: Hopefully I clarified that the rustdoc "groups" are not full-fledged teams and as such, to be part of them, you need to be a member of the rustdoc team.

src/rustdoc/membership.md

src/rustdoc/meetings.md

lolbinarycat

a few nitpicks

src/rustdoc/README.md

src/rustdoc/membership.md

src/rustdoc/proposals-and-stabilization.md

lolbinarycat · 2025-05-21T23:26:33Z

src/rustdoc/proposals-and-stabilization.md

+An FCP will be needed for any stabilization of small user-facing changes, like UI/UX changes, new
+command-line arguments, new attributes, etc. However, if the change is considered too big/important,


We should mention insta-stable GUI changes and the relaxed stability requirements thereof, since those aren't really a thing that exist anywhere else in rust project software.

rustdoc GUI is not considered stable (like the HTML/JS/CSS). We just try to limit its changes as much as possible. If it is a user-facing change, we want to go through an FCP to ensure that the reasons behind the change are valid and that majority agrees.

I think it would be good to clarify that UI/UX refers to the programmatic interface of rustdoc, not the web GUI (except for major changes).

src/rustdoc/meetings.md

apiraino

left a comment after a cursory read.

Great work @GuillaumeGomez !

src/rustdoc/calendar.md

src/rustdoc/proposals-and-stabilization.md

apiraino · 2025-05-22T11:27:28Z

src/rustdoc/proposals-and-stabilization.md

+### Can I work on code experimentally before a 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).


or as draft.

Slightly tangential, there is an ongoing discussion about the overlap between the label S-experimental and the "draft" state that GH offers. I don't know if this discussion is relevant to this bit of documentation, just wanted to mention it.

No clue, might be worth revisiting want this discussion has a conclusion.

src/rustdoc/proposals-and-stabilization.md

src/rustdoc/calendar.md

GuillaumeGomez · 2025-06-04T12:04:18Z

Clarified rustdoc team roles
Added more information about review policy
Fixed typos and links

lolbinarycat

looks pretty good, just a few nits about phrasing

src/rustdoc/membership.md

src/rustdoc/reviews.md

src/rustdoc/membership.md

jyn514 · 2025-06-05T03:17:12Z

src/rustdoc/membership.md

+Being part of the front-end group doesn't change your rustdoc team membership. However
+you will be assigned for reviews on front-end pull requests and on front-end FCPs.


i think i was just on mobile and didn't read enough of the context 😅

GuillaumeGomez · 2025-06-05T08:54:21Z

I think it's mostly ready now. I'm gonna switch it to full-fledged PR. I'll start the FCP in a few days if there is no new comment in-between.

rustbot · 2025-06-05T08:54:27Z

r? @Mark-Simulacrum

rustbot has assigned @Mark-Simulacrum.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

GuillaumeGomez · 2025-06-10T09:24:46Z

@rfcbot fcp merge

rfcbot · 2025-06-10T09:59:00Z

Team member @GuillaumeGomez has proposed to merge this. The next step is review by the rest of the tagged team members:

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

GuillaumeGomez · 2025-06-10T10:07:56Z

30 minutes latency, ok XD. Gonna edit my message haha.

src/rustdoc/proposals-and-stabilization.md

Add more information about review policy Fix typos and links

camelid

Thanks, this looks great! I left a few comments about small clarifications, but the overall charter looks excellent.

camelid · 2025-07-08T02:24:57Z

src/rustdoc/index.md

+you're looking for the [rustc-dev-guide](https://rustc-dev-guide.rust-lang.org/rustdoc.html).
+
+- [Calendar](./calendar.md)
+  - *How do I subscribe to the compiler team's calendar?*


nit:

Suggested change

- *How do I subscribe to the compiler team's calendar?*

- *How do I subscribe to the rustdoc team's calendar?*

camelid · 2025-07-08T02:25:37Z

src/rustdoc/meetings.md

+The rustdoc team hosts a meeting every second Monday on each month on the 
+[t-rustdoc/meetings channel on zulip](https://rust-lang.zulipchat.com/#narrow/channel/393423-t-rustdoc.2Fmeetings)
+at 21:00 CET (UTC+1) and CEST on summer (UTC+2).


Seems better to just link to the calendar here since this will probably fall out of date.

camelid · 2025-07-08T02:27:44Z

src/rustdoc/membership.md

+It also implies some obligations (in some cases, optional obligations):
+
+- Members are expected to respond to FCPs in maximum 4 weeks (28 days).
+- Members may take part in various other [maintainer activities] to help the team.


This doesn't have an associated link reference.

camelid · 2025-07-08T02:32:10Z

src/rustdoc/proposals-and-stabilization.md

+  - PRs are pull requests to the [`rust-lang/rust`][rust] repository and are a light-weight
+    proposal mechanism, suitable for most proposals. PRs are preferred when the proposal is
+    accompanied by a small patchset (such as stabilization of a compiler flag or addition of
+    a new target).


People also often open issues for feature proposals. Not critical to mention here, but maybe worth adding.

yeah, people often do that since we have no ACP/MCP type process.

camelid · 2025-07-08T02:33:09Z

src/rustdoc/proposals-and-stabilization.md

+An FCP will be needed for any stabilization of small user-facing changes, like UI/UX changes, new
+command-line arguments, new attributes, etc. However, if the change is considered too big/important,


I think it would be good to clarify that UI/UX refers to the programmatic interface of rustdoc, not the web GUI (except for major changes).

rfcbot · 2025-07-08T02:41:06Z

🔔 This is now entering its final comment period, as per the review above. 🔔

psst @GuillaumeGomez, I wasn't able to add the final-comment-period label, please do so.

lolbinarycat · 2025-07-09T20:16:20Z

I think that we should have a section for what happens if you get assigned as a reviewer on a PR that you don't have the time or experience to review properly, such as if it's a large change to a sub-component you haven't worked with before. Having a policy for this would probably be quite helpful for any new team members.

fmease · 2025-07-09T20:41:12Z

I think that we should have a section for what happens if you get assigned as a reviewer on a PR that you don't have the time or experience to review properly, such as if it's a large change to a sub-component you haven't worked with before.

This is already covered. See src/rustdoc/reviews.md:

Review Policy

The rustdoc team follows the same review policy as the compiler team. Take a look at
their chapter about it.

which delegates to compiler/reviews.md which in turn states (excerpts):

Basic Reviewing Requirements

There are a number of requirements that need to be met in order for reviewing to
be effective:

Reviewers must have a sufficient understanding of the code under review.
[…]

Reviewers must have a good idea on whether they are the right person to approve the change.
[…]

(see linked documents for more details)

fmease reviewed May 21, 2025

View reviewed changes

src/rustdoc/proposals-and-stabilization.md Outdated Show resolved Hide resolved

src/rustdoc/resources.md Show resolved Hide resolved

fmease reviewed May 21, 2025

View reviewed changes

src/rustdoc/README.md Outdated Show resolved Hide resolved

GuillaumeGomez force-pushed the rustdoc branch from 4929833 to 7fe9fc1 Compare May 21, 2025 15:24

fmease reviewed May 21, 2025

View reviewed changes

src/rustdoc/meetings.md Show resolved Hide resolved

src/rustdoc/membership.md Show resolved Hide resolved

GuillaumeGomez force-pushed the rustdoc branch from 7fe9fc1 to a6be7b7 Compare May 21, 2025 15:42

GuillaumeGomez mentioned this pull request May 21, 2025

Add rustdoc team to rust-forge and triagebot maintenance rust-lang/team#1831

Merged

notriddle requested changes May 21, 2025

View reviewed changes

src/rustdoc/proposals-and-stabilization.md Outdated Show resolved Hide resolved

src/rustdoc/proposals-and-stabilization.md Outdated Show resolved Hide resolved

aDotInTheVoid reviewed May 21, 2025

View reviewed changes

src/rustdoc/membership.md Outdated Show resolved Hide resolved

src/rustdoc/membership.md Outdated Show resolved Hide resolved

fmease reviewed May 21, 2025

View reviewed changes

fmease added T-rustdoc Team: Rustdoc needs-fcp This change is insta-stable, so needs a completed FCP to proceed. labels May 21, 2025

fmease added the S-waiting-on-team Status: Awaiting review/feedback/decision from relevant team(s) label May 21, 2025

Manishearth reviewed May 21, 2025

View reviewed changes

GuillaumeGomez force-pushed the rustdoc branch from a6be7b7 to fbbdf98 Compare May 21, 2025 18:54

GuillaumeGomez force-pushed the rustdoc branch from fbbdf98 to 506b368 Compare May 21, 2025 18:57

fmease reviewed May 21, 2025

View reviewed changes

src/rustdoc/membership.md Show resolved Hide resolved

src/rustdoc/meetings.md Outdated Show resolved Hide resolved

src/rustdoc/meetings.md Outdated Show resolved Hide resolved

src/rustdoc/meetings.md Outdated Show resolved Hide resolved

GuillaumeGomez force-pushed the rustdoc branch from 506b368 to 3b985ea Compare May 21, 2025 20:11

lolbinarycat reviewed May 21, 2025

View reviewed changes

lolbinarycat reviewed May 22, 2025

View reviewed changes

src/rustdoc/meetings.md Outdated Show resolved Hide resolved

GuillaumeGomez force-pushed the rustdoc branch from 3b985ea to 93e1cb9 Compare May 22, 2025 10:37

apiraino requested changes May 22, 2025

View reviewed changes

GuillaumeGomez force-pushed the rustdoc branch 2 times, most recently from 4da4ad9 to ab7ee18 Compare May 22, 2025 12:41

notriddle reviewed May 22, 2025

View reviewed changes

src/rustdoc/calendar.md Show resolved Hide resolved

GuillaumeGomez force-pushed the rustdoc branch 2 times, most recently from e92f236 to cc605f3 Compare May 22, 2025 20:53

lolbinarycat reviewed Jun 4, 2025

View reviewed changes

src/rustdoc/membership.md Outdated Show resolved Hide resolved

src/rustdoc/reviews.md Outdated Show resolved Hide resolved

jyn514 reviewed Jun 5, 2025

View reviewed changes

GuillaumeGomez force-pushed the rustdoc branch from b3ff41f to 106b11f Compare June 5, 2025 08:53

GuillaumeGomez marked this pull request as ready for review June 5, 2025 08:54

rustbot assigned Mark-Simulacrum Jun 5, 2025

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jun 5, 2025

aDotInTheVoid approved these changes Jun 5, 2025

View reviewed changes

fmease unassigned Mark-Simulacrum Jun 5, 2025

GuillaumeGomez force-pushed the rustdoc branch from 106b11f to e9b53f4 Compare June 5, 2025 19:21

This comment was marked as outdated.

Sign in to view

jieyouxu reviewed Jul 6, 2025

View reviewed changes

GuillaumeGomez force-pushed the rustdoc branch from e9b53f4 to 718483f Compare July 7, 2025 10:17

GuillaumeGomez added 4 commits July 7, 2025 12:18

Set rustdoc team as maintainer of the src/rustdoc folder

dcb01f3

Add rustdoc team processes

e53cb70

Change policy for automatic rustdoc alumni status

266e634

Clarify rustdoc team roles

a23c883

Add more information about review policy Fix typos and links

GuillaumeGomez force-pushed the rustdoc branch from 718483f to a23c883 Compare July 7, 2025 10:19

aDotInTheVoid mentioned this pull request Jul 7, 2025

Propose project goal to add a rustdoc team charter rust-lang/rust-project-goals#328

Open

camelid approved these changes Jul 8, 2025

View reviewed changes

camelid added the final-comment-period Will be merged/postponed/closed in ~10 calendar days unless new substational objections are raised. label Jul 8, 2025

Small improvements and clarifications

cafab69

		An FCP will be needed for any stabilization of small user-facing changes, like UI/UX changes, new
		command-line arguments, new attributes, etc. However, if the change is considered too big/important,

		Being part of the front-end group doesn't change your rustdoc team membership. However
		you will be assigned for reviews on front-end pull requests and on front-end FCPs.

	- How do I subscribe to the compiler team's calendar?
	- How do I subscribe to the rustdoc team's calendar?

Add rustdoc team processes #852

Are you sure you want to change the base?

Add rustdoc team processes #852

Uh oh!

Conversation

GuillaumeGomez commented May 21, 2025 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ehuss commented May 21, 2025

Uh oh!

Uh oh!

Uh oh!

aDotInTheVoid left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fmease commented May 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Manishearth left a comment

Choose a reason for hiding this comment

Uh oh!

GuillaumeGomez commented May 21, 2025

Uh oh!

GuillaumeGomez commented May 21, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lolbinarycat left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

apiraino left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

GuillaumeGomez commented Jun 4, 2025

Uh oh!

lolbinarycat left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GuillaumeGomez commented Jun 5, 2025

Uh oh!

rustbot commented Jun 5, 2025

GuillaumeGomez commented May 21, 2025 •

edited by rustbot

Loading

fmease commented May 21, 2025 •

edited

Loading

rfcbot commented Jun 10, 2025 •

edited by camelid

Loading

GuillaumeGomez commented Jun 10, 2025 •

edited

Loading

fmease commented Jul 9, 2025 •

edited

Loading