Add rustdoc team processes

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)

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/).
+
+- [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?*

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/

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.

src/rustdoc/membership.md

@@ -0,0 +1,116 @@
+# 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 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` mailing list. See
+  [this file](https://github.com/rust-lang/team/blob/HEAD/teams/all.toml) to check how subscriptions
+  to mailing lists work. It's a very low-volume mailing list (maybe a few emails per year), 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-fledge 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.
+
+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 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.
+
+The rustdoc team members will check to see if there are concerns with extending a membership
+invitation to the individual and after a week (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, 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.
+
+[team]: https://github.com/rust-lang/team

src/rustdoc/proposals-and-stabilization.md

@@ -0,0 +1,79 @@
+# 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?
+
+## What proposal/approval do I need?
+This section aims to exhaustively detail which proposal and approval is necessary for any given
+circumstance.
+
+[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/

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/ 
+[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

src/rustdoc/reviews.md

@@ -0,0 +1,4 @@
+# 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.

triagebot.toml

@@ -31,4 +31,5 @@ fallback = [
 "/src/libs" = ["libs"]
 "/src/platforms" = ["infra"]
 "/src/release" = ["release"]
+"/src/rustdoc" = ["rustdoc"]
 "/src/triagebot" = ["triagebot"]