From a0e75313e90ccb11a98b27c7ebf80768c558c2c3 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Mon, 17 Aug 2026 14:37:46 +0200 Subject: [PATCH 1/6] Add mdBook team processes --- src/SUMMARY.md | 4 + src/mdbook/index.md | 13 +++ src/mdbook/membership.md | 96 +++++++++++++++++++++++ src/mdbook/proposals-and-stabilization.md | 67 ++++++++++++++++ src/mdbook/reviews.md | 10 +++ triagebot.toml | 1 + 6 files changed, 191 insertions(+) create mode 100644 src/mdbook/index.md create mode 100644 src/mdbook/membership.md create mode 100644 src/mdbook/proposals-and-stabilization.md create mode 100644 src/mdbook/reviews.md 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..7c346c781 --- /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 rustdoc 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 rustdoc 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..67e8a7100 --- /dev/null +++ b/src/mdbook/membership.md @@ -0,0 +1,96 @@ +# 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-rustdoc + +## 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 also be subscribed to the `all@rust-lang.org` and `mdbook@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. + +## 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 inactive 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..184ae163f --- /dev/null +++ b/src/mdbook/proposals-and-stabilization.md @@ -0,0 +1,67 @@ +# 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 proposal (an RFC or an FCP) is added to the merge queue when it is approved to be merged. +- FCP + - A final comment period will require sign-off from a majority (all members minus 2) + of the mdBook 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 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 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. +- Pull Request (PR) + - Opening a pull request on the [`rust-lang/mdBook`][mdbbok] 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 UI/UX changes, +new command-line arguments, new attributes, etc. + +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 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 + equivalent tooks? +* **Alternatives, concerns, and key decisions:** Were there any alternatives considered? If so, why + did you pick this design? 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"] From aadfab081a8641d1e5b4c91c3452a89bb41fb53e Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Mon, 17 Aug 2026 15:05:30 +0200 Subject: [PATCH 2/6] Remove mention of mailing lists --- src/mdbook/membership.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/src/mdbook/membership.md b/src/mdbook/membership.md index 67e8a7100..6c80ea533 100644 --- a/src/mdbook/membership.md +++ b/src/mdbook/membership.md @@ -52,11 +52,6 @@ It also implies some obligations (in some cases, optional obligations): 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 also be subscribed to the `all@rust-lang.org` and `mdbook@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. ## How promotion decisions are made From 56beee114f0636c450fed17e944d47c47db1489c Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Mon, 17 Aug 2026 15:12:17 +0200 Subject: [PATCH 3/6] Add missing link definition --- src/mdbook/proposals-and-stabilization.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/mdbook/proposals-and-stabilization.md b/src/mdbook/proposals-and-stabilization.md index 184ae163f..731aa567a 100644 --- a/src/mdbook/proposals-and-stabilization.md +++ b/src/mdbook/proposals-and-stabilization.md @@ -27,7 +27,7 @@ the nature of the proposal, described below. 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`][mdbbok] repository is a lightweight + - 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 @@ -65,3 +65,6 @@ A good proposal will address the following: 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/ + From fdaa8f73d2eba7201f36cc37bb7ab8ae9c6b18b9 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Tue, 18 Aug 2026 14:52:55 +0200 Subject: [PATCH 4/6] Apply suggestions --- src/mdbook/membership.md | 3 ++- src/mdbook/proposals-and-stabilization.md | 5 ++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/mdbook/membership.md b/src/mdbook/membership.md index 6c80ea533..50a3d66cb 100644 --- a/src/mdbook/membership.md +++ b/src/mdbook/membership.md @@ -52,6 +52,7 @@ It also implies some obligations (in some cases, optional obligations): 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. ## How promotion decisions are made @@ -85,7 +86,7 @@ active as well. ### Automatic alumni status after 6 months of inactivity -If a member or maintainer has been inactive in mdBook for 6 months, they will be moved to the +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 index 731aa567a..66d5c714e 100644 --- a/src/mdbook/proposals-and-stabilization.md +++ b/src/mdbook/proposals-and-stabilization.md @@ -41,12 +41,12 @@ the nature of the proposal, described below. ### When are FCPs required? An FCP will be needed for any stabilization of user-facing changes, like UI/UX changes, -new command-line arguments, new attributes, etc. +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 a approval is gained? +### 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 @@ -67,4 +67,3 @@ A good proposal will address the following: did you pick this design? [mdbook]: https://github.com/rust-lang/mdBook/ - From 27bcdaa36ea02df12e010e867cb63556f32fd1d7 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 19 Aug 2026 18:18:26 +0200 Subject: [PATCH 5/6] Add mention of FCPs in memberhip privileges --- src/mdbook/membership.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/mdbook/membership.md b/src/mdbook/membership.md index 50a3d66cb..88a60530d 100644 --- a/src/mdbook/membership.md +++ b/src/mdbook/membership.md @@ -53,6 +53,7 @@ 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 From c3355ac1c75b12a0d1f98b1c12f5606f2a28b229 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Mon, 24 Aug 2026 12:24:36 +0200 Subject: [PATCH 6/6] Clarify FCP rules and remove rustdoc mentions --- src/mdbook/index.md | 4 ++-- src/mdbook/membership.md | 4 ++-- src/mdbook/proposals-and-stabilization.md | 18 ++++++++++-------- 3 files changed, 14 insertions(+), 12 deletions(-) diff --git a/src/mdbook/index.md b/src/mdbook/index.md index 7c346c781..3352532f2 100644 --- a/src/mdbook/index.md +++ b/src/mdbook/index.md @@ -6,8 +6,8 @@ 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 rustdoc team members and how do I join?* + - *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 rustdoc team? What approval is necessary for my change?* + - *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 index 88a60530d..36ca6e0e0 100644 --- a/src/mdbook/membership.md +++ b/src/mdbook/membership.md @@ -34,7 +34,7 @@ Being promoted to member implies a number of privileges: 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 +- 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]. @@ -45,7 +45,7 @@ It also implies some obligations (in some cases, optional obligations): - 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 +[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 diff --git a/src/mdbook/proposals-and-stabilization.md b/src/mdbook/proposals-and-stabilization.md index 66d5c714e..b0bde9db2 100644 --- a/src/mdbook/proposals-and-stabilization.md +++ b/src/mdbook/proposals-and-stabilization.md @@ -11,10 +11,11 @@ There are two mechanisms that the team can use to approve a proposal (not all ap are suitable for each method of making a proposal - see below): - Add to the merge queue - - A proposal (an RFC or an FCP) is added to the merge queue when it is approved to be merged. + - 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 a majority (all members minus 2) - of the mdBook team to approve a proposal and then a ten day waiting period. + - 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 @@ -23,9 +24,10 @@ There are three ways to propose a change to the mdBook team. The appropriate cho the nature of the proposal, described below. - Open a discussion on the [mdBook 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. + - 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. @@ -40,8 +42,8 @@ the nature of the proposal, described below. ### When are FCPs required? -An FCP will be needed for any stabilization of user-facing changes, like UI/UX changes, -new command-line arguments, new attributes, etc. It also includes breaking changes. +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.