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

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

notriddle · 2025-05-22T16:47:44Z

src/rustdoc/calendar.md

@@ -0,0 +1,3 @@
+# Calendar
+Rustdoc team's calendar is available in the Rust project's
+[`rust-lang/calendar`][calendar_repo] repository.


link ref not defined

Good catch, thanks!

camelid

Haven't had a chance yet to review the whole thing in depth yet, but left comments on a few parts. Should have time within the next few days to finish reading though. Glad we're doing this!

src/rustdoc/membership.md

camelid · 2025-05-22T23:17:25Z

src/rustdoc/membership.md

+If a member or maintainer has been inactive in rustdoc for 6 months, then we will ask them if
+they would like to go to alumni status. If they respond yes or do not respond, they can be placed on
+alumni status. If they would prefer to remain active, that is also fine, but they will get asked
+again periodically if they continue to be inactive.


It seems to me that ideally we'd have some kind of policy where people get put on alumni involuntarily (after a longer period of time, perhaps) if they aren't contributing at all, even if they say they want to stay on the team. Of course, if they explain their circumstance then there could be exceptions. And also given how alumni works, they could always be brought back to the team if/when they can contribute again.

I think first establish such a policy, then amend the documentation.

If it helps doing things consistently across teams, T-compiler policy is the same: after X time you might be asked if you want/can continue to contribute. Then I imagine we could open a patch on the team repo with some wording like this and give the inactive contributor a chance to 👍 / 👎

I think first establish such a policy, then amend the documentation.

I mean T-rustdoc doesn't have any policies at this point in time and this is the first ever document in which we formulate and thus make them.

Ok, so this PR is the discussion about policies and it's not the result of a process happened in another place/time - correct?¹

Footnotes

sorry if it looks like I'm jumping in your garden, just trying to have consistent processes across teams ↩

Absolutely. And your input is very welcome as you have more experience with compiler team policy. ;)

lolbinarycat · 2025-05-23T00:19:11Z

Kind of a nitpick, but should we do 10 days to match FCP length?

This is my first time hearing that's how long an FCP is, which is odd considering how many of my PRs have been through FCP.

I think there's a few causes for confusion:

this isn't written down in a visible enough spot
pFCP is a separate state which is even less documented, and does not seem to have an associated timeframe
the rfcbot command that makes a PR enter pFCP is fcp

GuillaumeGomez · 2025-05-23T12:02:30Z

Should be documented here I think. But yes, seems like it's missing. Sending them a PR.

GuillaumeGomez · 2025-05-23T12:07:24Z

Opened rust-lang/rfcbot-rs#329.

GuillaumeGomez · 2025-05-23T12:16:54Z

Applied @camelid's comments. Also, I updated the automatic alumni policy (did it in the second commit). Please take special attention to it and tell me if it looks ok to you. Maybe some extra thoughts from me about it: considering that any alumni can be brought back on the team on demand, I think it's pretty low barrier to keep it this way and they still are listed on the team's page (although in the alumnis list).

lolbinarycat · 2025-05-23T21:49:51Z

We kinda say this under the fcp policy, but I think it would be good to explicitly say "bugfixes tend to get merged faster than user-visible changes" somewhere (maybe under "the path to membership"), as that's something that might alleviate some confusion/frustration for new contributors, and it's a fact that's not immediately obvious, as projects with less stability commitments may not give these types of contributions extra consideration the way the rust project does.

lolbinarycat · 2025-05-23T23:43:39Z

I just realized code review is never mentioned anywhere in this. It probably should be.

GuillaumeGomez · 2025-05-29T13:05:12Z

I just realized code review is never mentioned anywhere in this. It probably should be.

What do you think should be mentioned?

jyn514 · 2025-05-29T12:51:40Z

src/rustdoc/README.md

+
+We use the Forge to document the team's processes, policies and working practices, if you'd like to
+read about how the compiler and rustdoc work and instructions on how to set up a development environment,
+you're looking for the [rustc-dev-guide](https://rustc-dev-guide.rust-lang.org/).


Suggested change

you're looking for the [rustc-dev-guide](https://rustc-dev-guide.rust-lang.org/).

you're looking for the [rustc-dev-guide](https://rustc-dev-guide.rust-lang.org/rustdoc.html).

jyn514 · 2025-05-29T14:36:29Z

src/rustdoc/membership.md

+It also implies some obligations (in some cases, optional obligations):
+
+- Members may take part in various other [maintainer activities] to help the team.
+- Members are held to a higher standard than ordinary folk when it comes to the [Code of
+  Conduct][CoC].


@Manishearth has said in the past something like "the minimum obligation for being a team member is responding promptly to FCPs" and i think that is a good rule that should end up in here.

(i don't have strong opinions on what "promptly" means but certainly i think it should be a month or less).

Good point, adding some numbers will be useful (and can be changed later on). I'll put one month for now.

jyn514 · 2025-05-29T14:39:18Z

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.


two thoughts about this:

i don't think being a team member should strongly imply that you have to do reviews (although certainly we can encourage it). again, i think the minimum is that people respond to FCPs. vice-versa, it seems fine for people on t-rustdoc to review frontend prs even if they're not on t-rustdoc-frontend.

"doesn't change your rustdoc team membership" is a little unclear - i think you meant "you don't have to be on t-rustdoc to be on t-rustdoc-frontend"? can you write that explicitly?

i don't think being a team member should strongly imply that you have to do reviews (although certainly we can encourage it). again, i think the minimum is that people respond to FCPs. vice-versa, it seems fine for people on t-rustdoc to review frontend prs even if they're not on t-rustdoc-frontend.

Indeed, clarifying text.

"doesn't change your rustdoc team membership" is a little unclear - i think you meant "you don't have to be on t-rustdoc to be on t-rustdoc-frontend"? can you write that explicitly?

No I really meant that you need to be part of the rustdoc team to be able to have the t-rustdoc-frontend role. Gonna clarify it.

No I really meant that you need to be part of the rustdoc team to be able to have the t-rustdoc-frontend role.

oh, interesting. my impression was that these "roles" are so that people can be involved with one part of rustdoc without having to be involved with all parts. if we require someone to be on t-rustdoc to have a role, they'd still be responsible for all FCP's, not only the FCP's related to their role. Is that intentional?

It's exactly what the roles are for: by default, if you're part of no role, you're not part of any FCP. For now we only have the front-end role which allows to have FCPs with 4 people. I'd like to extend it to the other parts of rustdoc (ie JSON and "everything else").

oh, i see! that model makes sense to me :) but the transition confuses me: after this charter is merged, who will be responsible for "FCPs that aren't for the frontend"? you said people won't be on FCP's unless they opt in, which wouldn't leave anyone left to do "general" FCPs.

If you're not part of any role, then you're not part of any FCP either, but that'd be strange, if someone is not part of any role, I don't think they should be on the team, or maybe there is a role missing and we can always add a new one if we think it makes sense. I listed 3 roles for the team:

front-end

JSON back-end

"everything else" (so that includes the HTML back-end, "cleaning" (rustc's to rustdoc's AST), rustdoc lints and more generally rustdoc internals)

Normally it covers all our current cases. If we want to make a general FCP, we can tag all the roles.

oh, i missed the "general" role. this all looks good to me then :) thanks for writing it up!

No problem! Do you think it needs clarifications? If you misunderstood this part, others might as well but not sure which part led to this confusion.

jyn514 · 2025-05-29T14:40:48Z

src/rustdoc/proposals-and-stabilization.md

+## What proposal/approval do I need?
+This section aims to exhaustively detail which proposal and approval is necessary for any given
+circumstance.
+


this looks like a stub?

Indeed, removing it.

jyn514 · 2025-05-29T14:41:18Z

src/rustdoc/resources.md

+If there are additional resources which would be useful to a contributor or compiler team member,
+feel free to submit a PR to add it here.
+
+[dev_guide]: https://rustc-dev-guide.rust-lang.org/ 


Suggested change

[dev_guide]: https://rustc-dev-guide.rust-lang.org/

[dev_guide]: https://rustc-dev-guide.rust-lang.org/rustdoc.html

jyn514 · 2025-05-29T14:42:11Z

src/rustdoc/membership.md

+- Internals: The internals of rustdoc: interacting with the compiler, doctests, generating
+  rustdoc internal code representation, parsing command line arguments, lints, etc.
+
+These groups are NOT full-fledge teams, and as such, to be part of any of these groups, you need to


Suggested change

These groups are NOT full-fledge teams, and as such, to be part of any of these groups, you need to

These groups are NOT full-fledged teams, and as such, to be part of any of these groups, you need to

lolbinarycat · 2025-05-29T19:02:16Z

What do you think should be mentioned [about code review]?

One of the main responsibilities and privileges of team members is approving pull requests
Code review from non members is welcome
New features are usually subject to more in depth review, such as an FCP

Add more information about review policy Fix typos and links

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

lolbinarycat · 2025-06-04T17:46:49Z

src/rustdoc/membership.md

@@ -45,6 +45,7 @@ Being promoted to member implies a number of privileges:

 It also implies some obligations (in some cases, optional obligations):

+- Members are expected to respond to FCPs in maximum 4 weeks.


Should we say 28/30 days instead? Using "weeks" as a unit of duration can be a bit confusing (like, if the FCP starts on friday, does that weekend start as a "week"?)

there are reasons why someone might want to set a deadline in terms of calendar weeks, but I don't think we want to, so we should just use days to avoid confusion.

lolbinarycat · 2025-06-04T17:55:05Z

src/rustdoc/reviews.md

@@ -2,3 +2,9 @@

 The rustdoc team follows the same review policy as the compiler team. Take a look at
 [their chapter](../compiler/reviews.md) about it.
+
+In addition, it's important to note that:
+ * Code reviews from non-members of the rustdoc team are welcome.


I think the phrasing here is a bit awkward, since "non-" is modifying the entire phrase "members of the rustdoc team".

I think writing this as "Anyone is welcome to provide their input as code review, even if you aren't a member of the rustdoc team" or something similar would be a bit more clear.

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 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

GuillaumeGomez force-pushed the rustdoc branch from ab7ee18 to e92f236 Compare May 22, 2025 20:52

Set rustdoc team as maintainer of the src/rustdoc folder

c52aaf2

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

camelid reviewed May 22, 2025

View reviewed changes

GuillaumeGomez mentioned this pull request May 23, 2025

Add missing information about FCP final comment period rust-lang/rfcbot-rs#329

Open

GuillaumeGomez added 2 commits May 23, 2025 14:13

Add rustdoc team processes

25e704d

Change policy for automatic rustdoc alumni status

9397f43

GuillaumeGomez force-pushed the rustdoc branch from cc605f3 to 9397f43 Compare May 23, 2025 12:14

jyn514 reviewed May 29, 2025

View reviewed changes

Clarify rustdoc team roles

b3ff41f

Add more information about review policy Fix typos and links

lolbinarycat reviewed Jun 4, 2025

View reviewed changes

	you're looking for the [rustc-dev-guide](https://rustc-dev-guide.rust-lang.org/).
	you're looking for the [rustc-dev-guide](https://rustc-dev-guide.rust-lang.org/rustdoc.html).

		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.

	[dev_guide]: https://rustc-dev-guide.rust-lang.org/
	[dev_guide]: https://rustc-dev-guide.rust-lang.org/rustdoc.html

	These groups are NOT full-fledge teams, and as such, to be part of any of these groups, you need to
	These groups are NOT full-fledged teams, and as such, to be part of any of these groups, you need to

		@@ -45,6 +45,7 @@ Being promoted to member implies a number of privileges:

		It also implies some obligations (in some cases, optional obligations):

		- Members are expected to respond to FCPs in maximum 4 weeks.

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

camelid 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!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

GuillaumeGomez commented May 21, 2025 •

edited by rustbot

Loading

fmease commented May 21, 2025 •

edited

Loading

fmease May 23, 2025 •

edited

Loading

GuillaumeGomez Jun 4, 2025 •

edited

Loading

jyn514 May 29, 2025 •

edited

Loading

GuillaumeGomez Jun 4, 2025 •

edited

Loading