diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 3a75def1..d927f9d5 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -67,6 +67,13 @@ - [Adding dependencies to the build environment](./docs-rs/add-dependencies.md) - [Self-hosting a docs.rs instance](./docs-rs/self-hosting.md) - [Maintenance procedures](./docs-rs/maintenance.md) +- [Rustdoc](./rustdoc/README.md) + - [Calendar](./rustdoc/calendar.md) + - [Meetings](./rustdoc/meetings.md) + - [Membership](./rustdoc/membership.md) + - [Resources](./rustdoc/resources.md) + - [Review Policy](./rustdoc/reviews.md) + - [Proposals, Approval and Stabilization](./rustdoc/proposals-and-stabilization.md) - [Governance](./governance/README.md) - [Leadership Council](./governance/council.md) - [Moderation](./governance/moderation.md) diff --git a/src/rustdoc/README.md b/src/rustdoc/README.md new file mode 100644 index 00000000..ea789a56 --- /dev/null +++ b/src/rustdoc/README.md @@ -0,0 +1,20 @@ +# Rustdoc +Rust's rustdoc team members are responsible for maintaining the Rustdoc tool, improving its performance +and considering the stabilization of rustdoc features. + +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/rustdoc.html). + +- [Calendar](./calendar.md) + - *How do I subscribe to the compiler team's calendar?* +- [Meetings](./meetings.md) + - *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?* +- [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?* diff --git a/src/rustdoc/calendar.md b/src/rustdoc/calendar.md new file mode 100644 index 00000000..5a564a16 --- /dev/null +++ b/src/rustdoc/calendar.md @@ -0,0 +1,5 @@ +# Calendar +Rustdoc team's calendar is available in the Rust project's +[`rust-lang/calendar`][calendar_repo] repository. + +[calendar_repo]: https://github.com/rust-lang/calendar/ diff --git a/src/rustdoc/meetings.md b/src/rustdoc/meetings.md new file mode 100644 index 00000000..17169683 --- /dev/null +++ b/src/rustdoc/meetings.md @@ -0,0 +1,16 @@ +# Meetings + +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). + +A new thread is open a month ahead of time to remind people who want to attend about the time +and the agenda. + +Anyone is open to participate to the meetings. + +If you want to add items to the agenda but you are not a member of the rustdoc team, please comment +on the Zulip thread for the next meeting about the items you want to see discussed. A member of the +rustdoc team will take a look and decide if they can be added to the agenda and what their priority +is. If the item was already discussed, they will provide either explanations or a link to where the +previous discussion happened. diff --git a/src/rustdoc/membership.md b/src/rustdoc/membership.md new file mode 100644 index 00000000..2c7656ae --- /dev/null +++ b/src/rustdoc/membership.md @@ -0,0 +1,119 @@ +# Membership +This section discusses membership in the rustdoc team. + +## The path to membership + +People who are looking to contribute on the rustdoc tool generally start on either fixing bugs +or implementing a new feature. If you need guidance or help, don't hesitate to ask on the +[t-rustdoc channel on Zulip](https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc)! + +## Rustdoc member +Once an individual has been contributing regularly for some time, they can be promoted to the +level of a **rustdoc team member** (see the section on [how decisions are made][hdam] below). +This title indicates that they are someone who contributes regularly. + +It is hard to define the precise conditions when such a promotion is appropriate. Being promoted +to member is not just a function of checking various boxes. But the general sense is that someone +is ready when they have demonstrated three things: + +- "Staying power" -- the person should be contributing on a regular basis in some way. This might + for example mean that they have completed a few projects. +- "Independence and familiarity" -- they should be acting somewhat independently when taking on + tasks, at least within the scope of their "rustdoc area". They should plausibly be able to mentor + others on simple PRs. +- "Cordiality" -- rustdoc team members will be part of the Rust organization and are held to a + higher standard with respect to the [Code of Conduct][CoC]. They should not only obey the + letter of the CoC but also its spirit. + +[CoC]: https://www.rust-lang.org/policies/code-of-conduct + +Being promoted to member implies a number of privileges: + +- 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 + perf/rustc-timer and other similar bots. See the documentation for `bors` and `r+` + [here](https://rustc-dev-guide.rust-lang.org/contributing.html#r-1). + + Tip: some baseline rules around bors permissions are: don't do a `try` build unless you have + done a check for malicious code first and don't `r+` unless you are reasonably confident that + you can effectively review the code in question. +- Rustdoc team members are members of the Rust organization so they can modify labels and be + assigned to issues. +- Members become a part of the `rust-lang/rustdoc` team on GitHub, so that they receive pings + when people are looking to address the team as a whole. +- Members are listed on the [rust-lang.org web page]. + +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. +- Members are held to a higher standard than ordinary folk when it comes to the [Code of + Conduct][CoC]. + +[rust-lang.org web page]: https://www.rust-lang.org/governance/teams/dev-tools#team-rustdoc + +## What it means to be a rustdoc member +Once you're a member of the rustdoc team, a number of events will happen: + +- You will gain access to a private Zulip stream, where internal discussions happen. +- You will also be subscribed to the `all@rust-lang.org` and `rustdoc@rust-lang.org` mailing lists. + See [this file](https://github.com/rust-lang/team/blob/HEAD/teams/all.toml) to check how + subscriptions to mailing lists work. Both are very low-volume mailing list (maybe a few emails per + year). About `all@rust-lang.org`: it's a way to communicate things to all contributors. We will + not send you spam from this address. + +## Roles in the rustdoc team + +Rustdoc has multiple different areas and team members are not working on all of them. Currently +we have three main areas: + +- Front-end: Everything related to HTML/CSS/JS +- JSON backend: Work on the `--output-format=json` backend. +- 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-fledged teams, and as such, to be part of any of these groups, you need to +be a member of the rustdoc team. + +For now, only the front-end group has an official status in the +[team repository](https://github.com/rust-lang/team) and is called `rustdoc-frontend`. If a rustdoc +team member is interested to be part of this group, they can ask to be added into it. + +Let's take the front-end group as an example. It is a part of the rustdoc team, so you need to be a +member of the rustdoc team to be able to join this group. Being part of the front-end group means +you are encouraged to be part of the review rotations for front-end pull requests and you will need +to respond on front-end FCPs. + +## How promotion decisions are made +[hdam]: #how-promotion-decisions-are-made + +After an individual has been contributing to rustdoc for a while, they may be nominated in the +private Zulip rustdoc team channel by an existing team member. All nominations **must** be done in +the private Zulip rustdoc team channel. + +The rustdoc team members will check to see if there are concerns with extending a membership +invitation to the individual and after 10 days (barring no objections), an invitation will be +extended. + +If the invitation is accepted by the individual, the rustdoc team leads will update the [team] +repository to reflect their new role. + +## 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.** + +People in alumni status can ask to return to "active" status at any time. This request would +ordinarily be granted automatically barring extraordinary circumstances. + +People in alumni status are still members of the team at the level they previously attained and +they may publicly indicate that, though they should indicate the time period for which they were +active as well. + +### Automatic alumni status after 6 months of inactivity +If a member or maintainer has been inactive in rustdoc for 6 months, they will be moved to the +alumni status. + +[team]: https://github.com/rust-lang/team diff --git a/src/rustdoc/proposals-and-stabilization.md b/src/rustdoc/proposals-and-stabilization.md new file mode 100644 index 00000000..bbd34135 --- /dev/null +++ b/src/rustdoc/proposals-and-stabilization.md @@ -0,0 +1,75 @@ +# Proposals, Approvals and Stabilization +It is very common to need to gather feedback and approval when contributing to rustdoc, either +for permission to proceed with an experiment or refactoring, or when stabilizing a feature. This +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 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 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. + +## Proposals +There are three 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 + 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. +- Request For Comments (RFC) + - RFCs are pull requests to the [`rust-lang/rfcs`][rfcs] repository and are a heavy-weight + proposal mechanism, reserved for significant changes. + - RFC proposals can only be approved by *FCPs*. +- Pull Request (PR) + - 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). + - PR proposals can be approved by *FCPs* or *r+*. + +[rustdoc zulip thread]: https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc + +### When are FCPs/RFCs required? + +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, +an RFC will need to be written and approved before the change will be accepted. + +When opening an FCP, make sure only the relevant subteam is labeled on the issue, to avoid pinging +people with changes they aren't interested in. + +### What happens if someone makes a contribution that requires an approval and doesn't have one? +If the approval required for the contribution requires an RFC, then the contribution +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? +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). + +## What makes a good proposal? +A good proposal will address the following: + +* **Motivation:** Why is this proposal necessary? What problem does it solve? Why is that problem + important? +* **Design:** What are you proposing? +* **Implementation notes:** You don't have to talk about the implementation normally, but if there + are any key things to note (i.e., it was very invasive to implement), you might note them here. +* **Precedent, links, and related material:** Have there been similar proposals on other + documentation websites, like [Haddock], [Wikipedia], [Racket]? +* **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/resources.md b/src/rustdoc/resources.md new file mode 100644 index 00000000..9fc24573 --- /dev/null +++ b/src/rustdoc/resources.md @@ -0,0 +1,16 @@ +# Resources +There are various resources which are useful to contributors and team members. + +- [rustdoc internals](https://rustc-dev-guide.rust-lang.org/rustdoc-internals.html) +- [rustc Developer Guide][dev_guide] + - Documentation on compiler internals and setting up a developer environment. +- [rustc Generated Documentation][rustc] +- [rustdoc Generated Documentation][rustdoc] + - rustdoc output for the compiler sources + +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/rustdoc.html +[rustc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/index.html +[rustdoc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc/index.html diff --git a/src/rustdoc/reviews.md b/src/rustdoc/reviews.md new file mode 100644 index 00000000..f95537e0 --- /dev/null +++ b/src/rustdoc/reviews.md @@ -0,0 +1,11 @@ +# Review Policy + +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: + * Anyone is welcome to provide their input as code review, even if you aren't a member of the + rustdoc team. + * Only team members can approve pull requests for being merged. + * New features are usually subject to more in depth review and might need to go through an RFC or + an FCP. diff --git a/triagebot.toml b/triagebot.toml index acef24bd..cd57fedf 100644 --- a/triagebot.toml +++ b/triagebot.toml @@ -31,4 +31,5 @@ fallback = [ "/src/libs" = ["libs"] "/src/platforms" = ["infra"] "/src/release" = ["release"] +"/src/rustdoc" = ["rustdoc"] "/src/triagebot" = ["triagebot"]