-
Notifications
You must be signed in to change notification settings - Fork 194
Add rustdoc team processes #852
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: master
Are you sure you want to change the base?
Conversation
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? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for working on this! I'm very happy to see this written down.
(This PR will obviously need a T-rustdoc FCP to make it official once most things have been sufficiently fleshed out) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
overall this seems pretty good!
Absolutely! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
a few nitpicks
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
left a comment after a cursory read.
Great work @GuillaumeGomez !
### 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). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No clue, might be worth revisiting want this discussion has a conclusion.
4da4ad9
to
ab7ee18
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
Outdated
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 👍 / 👎
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Absolutely. And your input is very welcome as you have more experience with compiler team policy. ;)
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:
|
Should be documented here I think. But yes, seems like it's missing. Sending them a PR. |
Opened rust-lang/rfcbot-rs#329. |
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). |
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. |
I just realized code review is never mentioned anywhere in this. It probably should be. |
What do you think should be mentioned? |
src/rustdoc/README.md
Outdated
|
||
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/). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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). |
src/rustdoc/membership.md
Outdated
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]. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@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).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good point, adding some numbers will be useful (and can be changed later on). I'll put one month for now.
src/rustdoc/membership.md
Outdated
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- 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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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").
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
oh, i missed the "general" role. this all looks good to me then :) thanks for writing it up!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i think i was just on mobile and didn't read enough of the context 😅
## What proposal/approval do I need? | ||
This section aims to exhaustively detail which proposal and approval is necessary for any given | ||
circumstance. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this looks like a stub?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Indeed, removing it.
src/rustdoc/resources.md
Outdated
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/ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[dev_guide]: https://rustc-dev-guide.rust-lang.org/ | |
[dev_guide]: https://rustc-dev-guide.rust-lang.org/rustdoc.html |
src/rustdoc/membership.md
Outdated
- 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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 |
|
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
looks pretty good, just a few nits about phrasing
src/rustdoc/membership.md
Outdated
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i think i was just on mobile and didn't read enough of the context 😅
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 has assigned @Mark-Simulacrum. Use |
Add more information about review policy Fix typos and links
cc @rust-lang/rustdoc
Rendered