diff --git a/src/SUMMARY.md b/src/SUMMARY.md index df50a1a70..bb4a24316 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -81,6 +81,10 @@ - [Resources](./rustdoc/resources.md) - [Review Policy](./rustdoc/reviews.md) - [Proposals, Approval and Stabilization](./rustdoc/proposals-and-stabilization.md) +- [mdBook](./mdbook/index.md) + - [Membership](./mdbook/membership.md) + - [Review Policy](./mdbook/reviews.md) + - [Proposals, Approval and Stabilization](./mdbook/proposals-and-stabilization.md) - [Governance](./governance/index.md) - [Leadership Council](./governance/council.md) - [Moderation](./governance/moderation.md) diff --git a/src/mdbook/index.md b/src/mdbook/index.md new file mode 100644 index 000000000..3352532f2 --- /dev/null +++ b/src/mdbook/index.md @@ -0,0 +1,13 @@ +# mdBook + +Rust's mdBook team members are responsible for maintaining the mdBook tool, improving its performance +and considering the stabilization of mdBook features. + +We use the Forge to document the team's processes, policies and working practices. + +- [Membership](./membership.md) + - *What is expected of mdBook team members and how do I join?* +- [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 mdBook team? What approval is necessary for my change?* diff --git a/src/mdbook/membership.md b/src/mdbook/membership.md new file mode 100644 index 000000000..36ca6e0e0 --- /dev/null +++ b/src/mdbook/membership.md @@ -0,0 +1,93 @@ +# Membership +This section discusses membership in the mdBook team. + +## The path to membership + +People who are looking to contribute on the mdBook tool generally start on either fixing bugs, +implementing a new feature or reviewing open pull requests. If you need guidance or help, don't +hesitate to ask on the [t-mdbook channel on Zulip](https://rust-lang.zulipchat.com/#narrow/channel/507422-t-mdbook)! + +## mdBook member + +Once an individual has been contributing regularly for some time, they can be promoted to the +level of a **mdBook 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 "mdBook area". They should plausibly be able to mentor + others on simple PRs. +- "Cordiality" -- mdBook 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 can add pull requests to the merge queue and can do reviews (they are expected to + use those powers appropriately, as discussed previously). +- mdBook 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/mdbook` 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-mdbook + +## What it means to be a mdBook team member + +Once you're a member of the mdBook team, a number of events will happen: + +- You will gain access to a private Zulip stream, where internal discussions happen. +- You will be able to add pull requests to the merge queue. +- You will be able to start FCPs, but also approve and/or raise concerns on them. + +## How promotion decisions are made + +[hdam]: #how-promotion-decisions-are-made + +After an individual has been contributing to mdBook for a while, they may be nominated in the +private Zulip mdBook team channel by an existing team member. All nominations **must** be done in +the private Zulip mdBook team channel. + +The mdBook 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 mdBook team leads will update the [team] +repository to reflect their new role. + +## Alumni status + +If at any time a mdBook 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 the possibility to add pull requests to the merge queue anymore. **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 nonresponsive in mdBook for 6 months, they will be moved to the +alumni status. + +[team]: https://github.com/rust-lang/team diff --git a/src/mdbook/proposals-and-stabilization.md b/src/mdbook/proposals-and-stabilization.md new file mode 100644 index 000000000..b0bde9db2 --- /dev/null +++ b/src/mdbook/proposals-and-stabilization.md @@ -0,0 +1,71 @@ +# Proposals, Approvals and Stabilization + +It is very common to need to gather feedback and approval when contributing to mdBook, either +for permission to proceed with an experiment or refactoring, or when adding a new feature. This +document aims to summarise the various processes that the mdBook 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): + +- Add to the merge queue + - A pull request is added to the merge queue when it is approved to be merged. +- FCP + - A final comment period will require sign-off from members of the mdBook (exact number depends + on the size of the team, refer to the FCP process to know exactly) 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 mdBook team. The appropriate choice depends on +the nature of the proposal, described below. + +- Open a discussion on the [mdBook zulip thread]. + - This is the preferred way. It reduces the risk of contributors losing 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. +- Pull Request (PR) + - Opening a pull request on the [`rust-lang/mdBook`][mdbook] repository is a lightweight + mechanism suitable for most proposals. + - PR proposals can be approved by *FCPs* or *by being added to the merge queue*. See + *When are FCPs required?* section below when *being added to the merge queue* isn't + sufficient alone. +- Issues + - Opening an issue on the [`rust-lang/mdBook`][mdbook] repository are also a good starting + point if you don't know which of the previous ways is the best fit. + +[mdBook zulip thread]: https://rust-lang.zulipchat.com/#narrow/channel/507422-t-mdbook + +### When are FCPs required? + +An FCP will be needed for any stabilization of user-facing changes, like major UI/UX +changes, new command-line arguments, new attributes, etc. It also includes breaking changes. + +When starting an FCP, make sure only the relevant subteam is labeled on the issue/PR, to avoid +pinging people with changes they aren't interested in. + +### Can I work on code experimentally before an 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 + equivalent tooks? +* **Alternatives, concerns, and key decisions:** Were there any alternatives considered? If so, why + did you pick this design? + +[mdbook]: https://github.com/rust-lang/mdBook/ diff --git a/src/mdbook/reviews.md b/src/mdbook/reviews.md new file mode 100644 index 000000000..68bd78fff --- /dev/null +++ b/src/mdbook/reviews.md @@ -0,0 +1,10 @@ +# Review Policy + +The mdBook 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 + mdBook 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 FCP. diff --git a/triagebot.toml b/triagebot.toml index 315f447df..f5290337f 100644 --- a/triagebot.toml +++ b/triagebot.toml @@ -29,6 +29,7 @@ fallback = [ "/src/infra" = ["infra"] "/src/lang" = ["lang"] "/src/libs" = ["libs"] +"/src/mdbook" = ["mdbook"] "/src/platforms" = ["infra"] "/src/release" = ["release"] "/src/rustc-dev-guide" = ["rustc-dev-guide"]