Skip to content

Commit 93e1cb9

Browse files
GuillaumeGomezGuillaumeGomez
committed
Add rustdoc team processes
1 parent 1a5d020 commit 93e1cb9

8 files changed

+260
-0
lines changed

‎src/SUMMARY.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,13 @@
6666
- [Adding dependencies to the build environment](./docs-rs/add-dependencies.md)
6767
- [Self-hosting a docs.rs instance](./docs-rs/self-hosting.md)
6868
- [Maintenance procedures](./docs-rs/maintenance.md)
69+
- [Rustdoc](./rustdoc/README.md)
70+
- [Calendar](./rustdoc/calendar.md)
71+
- [Meetings](./rustdoc/meetings.md)
72+
- [Membership](./rustdoc/membership.md)
73+
- [Resources](./rustdoc/resources.md)
74+
- [Review Policy](./rustdoc/reviews.md)
75+
- [Proposals, Approval and Stabilization](./rustdoc/proposals-and-stabilization.md)
6976
- [Governance](./governance/README.md)
7077
- [Leadership Council](./governance/council.md)
7178
- [Moderation](./governance/moderation.md)

‎src/rustdoc/README.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Rustdoc
2+
Rust's rustdoc team members are responsible for maintaining the Rustdoc tool, improving its performance
3+
and considering the stabilization of rustdoc features.
4+
5+
We use the Forge to document the team's processes, policies and working practices, if you'd like to
6+
read about how the compiler and rustdoc work and instructions on how to set up a development environment,
7+
you're looking for the [rustc-dev-guide](https://rustc-dev-guide.rust-lang.org/).
8+
9+
- [Calendar](./calendar.md)
10+
- *How do I subscribe to the compiler team's calendar?*
11+
- [Meetings](./meetings.md)
12+
- *What meetings do the rustdoc team run and how can I attend?*
13+
- [Membership](./membership.md)
14+
- *What is expected of rustdoc team members and how do I join?*
15+
- [Resources](./resources.md)
16+
- *What useful resources are available for contributors and team members?*
17+
- [Review Policy](./reviews.md)
18+
- *How do I make a contribution which is easy to review? How do I start reviewing as a team member?*
19+
- [Proposals, Approval and Stabilization](./proposals-and-stabilization.md)
20+
- *How do I propose a change to the rustdoc team? What approval is necessary for my change?*

‎src/rustdoc/calendar.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Calendar
2+
Rustdoc team's calendar is available in the Rust project's
3+
[`rust-lang/calendar`][calendar_repo] repository.
4+
5+
Currently, the rustdoc team only has regular meetings.

‎src/rustdoc/meetings.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Meetings
2+
3+
The rustdoc team hosts a meeting every second Monday on each month on the
4+
[t-rustdoc/meetings channel on zulip](https://rust-lang.zulipchat.com/#narrow/channel/393423-t-rustdoc.2Fmeetings)
5+
at 21:00 CET (UTC+1) and CEST on summer (UTC+2).
6+
7+
A new thread is open a month ahead of time to remind people who want to attend about the time
8+
and the agenda.
9+
10+
Anyone is open to participate to the meetings.
11+
12+
If you want to add items to the agenda but you are not a member of the rustdoc team, please comment
13+
on the Zulip thread for the next meeting about the items you want to see discussed. A member of the
14+
rustdoc team will take a look and decide if they can be added to the agenda and what their priority
15+
is. If the item was already discussed, they will provide either explanations or a link to where the
16+
previous discussion happened.

‎src/rustdoc/membership.md

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Membership
2+
This section discusses membership in the rustdoc team.
3+
4+
## The path to membership
5+
6+
People who are looking to contribute on the rustdoc tool generally start on either fixing bugs
7+
or implementing a new feature. If you need guidance or help, don't hesitate to ask on the
8+
[t-rustdoc channel on Zulip](https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc)!
9+
10+
## Rustdoc member
11+
Once an individual has been contributing regularly for some time, they can be promoted to the
12+
level of a **rustdoc team member** (see the section on [how decisions are made][hdam] below).
13+
This title indicates that they are someone who contributes regularly.
14+
15+
It is hard to define the precise conditions when such a promotion is appropriate. Being promoted
16+
to member is not just a function of checking various boxes. But the general sense is that someone
17+
is ready when they have demonstrated three things:
18+
19+
- "Staying power" -- the person should be contributing on a regular basis in some way. This might
20+
for example mean that they have completed a few projects.
21+
- "Independence and familiarity" -- they should be acting somewhat independently when taking on
22+
tasks, at least within the scope of their "rustdoc area". They should plausibly be able to mentor
23+
others on simple PRs.
24+
- "Cordiality" -- rustdoc team members will be part of the Rust organization and are held to a
25+
higher standard with respect to the [Code of Conduct][CoC]. They should not only obey the
26+
letter of the CoC but also its spirit.
27+
28+
[CoC]: https://www.rust-lang.org/policies/code-of-conduct
29+
30+
Being promoted to member implies a number of privileges:
31+
32+
- Members have `r+` (approve a pull request) privileges and can do reviews (they are expected to
33+
use those powers appropriately, as discussed previously). They also have access to control
34+
perf/rustc-timer and other similar bots. See the documentation for `bors` and `r+`
35+
[here](https://rustc-dev-guide.rust-lang.org/contributing.html#r-1).
36+
37+
Tip: some baseline rules around bors permissions are: don't do a `try` build unless you have
38+
done a check for malicious code first and don't `r+` unless you are reasonably confident that
39+
you can effectively review the code in question.
40+
- Rustdoc team members are members of the Rust organization so they can modify labels and be
41+
assigned to issues.
42+
- Members become a part of the `rust-lang/rustdoc` team on GitHub, so that they receive pings
43+
when people are looking to address the team as a whole.
44+
- Members are listed on the [rust-lang.org web page].
45+
46+
It also implies some obligations (in some cases, optional obligations):
47+
48+
- Members may take part in various other [maintainer activities] to help the team.
49+
- Members are held to a higher standard than ordinary folk when it comes to the [Code of
50+
Conduct][CoC].
51+
52+
[rust-lang.org web page]: https://www.rust-lang.org/governance/teams/dev-tools#team-rustdoc
53+
54+
## What it means to be a rustdoc member
55+
Once you're a member of the rustdoc team, a number of events will happen:
56+
57+
- You will gain access to a private Zulip stream, where internal discussions happen.
58+
- You will also be subscribed to the `all@rust-lang.org` mailing list. See
59+
[this file](https://github.com/rust-lang/team/blob/HEAD/teams/all.toml) to check how subscriptions
60+
to mailing lists work. It's a very low-volume mailing list (maybe a few emails per year), it's a
61+
way to communicate things to all contributors. We will not send you spam from this address.
62+
63+
## Roles in the rustdoc team
64+
65+
Rustdoc has multiple different areas and team members are not working on all of them. Currently
66+
we have three main areas:
67+
68+
- Front-end: Everything related to HTML/CSS/JS
69+
- JSON backend: Work on the `--output-format=json` backend.
70+
- Internals: The internals of rustdoc: interacting with the compiler, doctests, generating
71+
rustdoc internal code representation, parsing command line arguments, lints, etc.
72+
73+
These groups are NOT full-fledge teams, and as such, to be part of any of these groups, you need to
74+
be a member of the rustdoc team.
75+
76+
For now, only the front-end group has an official status in the
77+
[team repository](https://github.com/rust-lang/team) and is called `rustdoc-frontend`. If a rustdoc
78+
team member is interested to be part of this group, they can ask to be added into it.
79+
80+
Being part of the front-end group doesn't change your rustdoc team membership. However
81+
you will be assigned for reviews on front-end pull requests and on front-end FCPs.
82+
83+
## How promotion decisions are made
84+
[hdam]: #how-promotion-decisions-are-made
85+
86+
After an individual has been contributing to rustdoc for a while, they may be nominated in the
87+
private Zulip rustdoc team channel by an existing team member.
88+
89+
The rustdoc team members will check to see if there are concerns with extending a membership
90+
invitation to the individual and after a week (barring no objections), an invitation will be
91+
extended.
92+
93+
If the invitation is accepted by the individual, the rustdoc team leads will update the [team]
94+
repository to reflect their new role.
95+
96+
## Alumni status
97+
If at any time a rustdoc team member wishes to take a break from participating, they can opt to put
98+
themselves into alumni status. When in alumni status, they will be removed from
99+
GitHub aliases and the like, so that they need not be bothered with pings and messages. They will
100+
also not have r+ privileges. **Alumni members will however still remain members of the GitHub
101+
org overall.**
102+
103+
People in alumni status can ask to return to "active" status at any time. This request would
104+
ordinarily be granted automatically barring extraordinary circumstances.
105+
106+
People in alumni status are still members of the team at the level they previously attained and
107+
they may publicly indicate that, though they should indicate the time period for which they were
108+
active as well.
109+
110+
### Automatic alumni status after 6 months of inactivity
111+
If a member or maintainer has been inactive in rustdoc for 6 months, then we will ask them if
112+
they would like to go to alumni status. If they respond yes or do not respond, they can be placed on
113+
alumni status. If they would prefer to remain active, that is also fine, but they will get asked
114+
again periodically if they continue to be inactive.
115+
116+
[team]: https://github.com/rust-lang/team

‎src/rustdoc/proposals-and-stabilization.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Proposals, Approvals and Stabilization
2+
It is very common to need to gather feedback and approval when contributing to rustdoc, either
3+
for permission to proceed with an experiment or refactoring, or when stabilizing a feature. This
4+
document aims to summarise the various processes that the rustdoc team has for making approval
5+
decisions and when each should be used.
6+
7+
## Approvals
8+
There are three mechanisms that the team can use to approve a proposal (not all approval mechanisms
9+
are suitable for each method of making a proposal - see below):
10+
11+
- r+
12+
- A proposal is r+'d when it is approved to be merged.
13+
- r+ can only be used to approve a PR.
14+
- FCP
15+
- A final comment period will require sign-off from a majority of the rustdoc team to approve
16+
a proposal and then a ten day waiting period.
17+
- FCPs can be used to approve any form of proposal.
18+
19+
## Proposals
20+
There are three ways to propose a change to the rustdoc team. The appropriate choice depends on
21+
the nature of the proposal, described below.
22+
23+
- Open a discussion on the [rustdoc zulip thread].
24+
- This is the preferred way. It allows to prevent users to lose too much time implementing
25+
something if in the end, the team will ask major changes or even refuse it. After the
26+
discussion, if accepted and depending on the change, an RFC or a PR will be the next step.
27+
- Request For Comments (RFC)
28+
- RFCs are pull requests to the [`rust-lang/rfcs`][rfcs] repository and are a heavy-weight
29+
proposal mechanism, reserved for significant changes.
30+
- RFC proposals can only be approved by *FCPs*.
31+
- Pull Request (PR)
32+
- PRs are pull requests to the [`rust-lang/rust`][rust] repository and are a light-weight
33+
proposal mechanism, suitable for most proposals. PRs are preferred when the proposal is
34+
accompanied by a small patchset (such as stabilization of a compiler flag or addition of
35+
a new target).
36+
- PR proposals can be approved by *FCPs* or *r+*.
37+
38+
[rustdoc zulip thread]: https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc
39+
40+
### When are FCPs/RFCs required?
41+
42+
An FCP will be needed for any stabilization of small user-facing changes, like UI/UX changes, new
43+
command-line arguments, new attributes, etc. However, if the change is considered too big/important,
44+
an RFC will need to be written and approved before the change will be accepted.
45+
46+
When opening an FCP, make sure only the relevant subteam is labeled on the issue, to avoid pinging
47+
people with changes they aren't interested in.
48+
49+
### What happens if someone makes a contribution that requires an approval and doesn't have one?
50+
If the approval required for the contribution requires an RFC, then the contribution
51+
should be closed or marked as blocked, with a request to create an RFC first. If approval of
52+
a PR is acceptable for the specific contribution (see below), then the approval process can begin.
53+
54+
### Can I work on code experimentally before a approval is gained?
55+
Of course! You are free to work on PRs or write code. But those PRs should be marked as
56+
experimental and they should not land, nor should anyone be expected to review them (unless
57+
folks want to).
58+
59+
## What makes a good proposal?
60+
A good proposal will address the following:
61+
62+
* **Motivation:** Why is this proposal necessary? What problem does it solve? Why is that problem
63+
important?
64+
* **Design:** What are you proposing?
65+
* **Implementation notes:** You don't have to talk about the implementation normally, but if there
66+
are any key things to note (i.e., it was very invasive to implement), you might note them here.
67+
* **Precedent, links, and related material:** Have there been similar proposals on other
68+
documentation websites, like Haddock, Wikipedia, Racket?
69+
* **Alternatives, concerns, and key decisions:** Were there any alernatives considered? If so, why
70+
did you pick this design?
71+
72+
## What proposal/approval do I need?
73+
This section aims to exhaustively detail which proposal and approval is necessary for any given
74+
circumstance.
75+
76+
[rfcs]: https://github.com/rust-lang/rfcs

‎src/rustdoc/resources.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Resources
2+
There are various resources which are useful to contributors and team members.
3+
4+
- [rustdoc internals](https://rustc-dev-guide.rust-lang.org/rustdoc-internals.html)
5+
- [rustc Developer Guide][dev_guide]
6+
- Documentation on compiler internals and setting up a developer environment.
7+
- [rustc Generated Documentation][rustc]
8+
- [rustdoc Generated Documentation][rustdoc]
9+
- rustdoc output for the compiler sources
10+
11+
If there are additional resources which would be useful to a contributor or compiler team member,
12+
feel free to submit a PR to add it here.
13+
14+
[dev_guide]: https://rustc-dev-guide.rust-lang.org/
15+
[rustc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/index.html
16+
[rustdoc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc/index.html

‎src/rustdoc/reviews.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Review Policy
2+
3+
The rustdoc team follows the same review policy as the compiler team. Take a look at
4+
[their chapter](../compiler/reviews.md) about it.

0 commit comments

Comments
 (0)