Add mdBook team processes - #1095
Conversation
rustbot
added
the
S-waiting-on-review
|
rustbot has assigned @Mark-Simulacrum. Use Why was this reviewer chosen?The reviewer was selected based on:
|
| - 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 |
There was a problem hiding this comment.
I would personally not embed emails like this in public docs, just an invitation for more spam to be sent to them.
There was a problem hiding this comment.
Fair enough, removed.
| ### 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. |
There was a problem hiding this comment.
You should probably mention breaking changes. Those definitely require an FCP, since mdBook doesn’t have RFCs or a Rust style stability system.
| 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? |
There was a problem hiding this comment.
| ### Can I work on code experimentally before a approval is gained? | |
| ### Can I work on code experimentally before an approval is gained? |
| did you pick this design? | ||
|
|
||
| [mdbook]: https://github.com/rust-lang/mdBook/ | ||
|
|
There was a problem hiding this comment.
|
Applied suggestions. |
There was a problem hiding this comment.
This document flows a bit strange to me, and I guess the problem is shared with the rustdoc version as well. Essentially, it seems worded as a path to membership, rather than starting with, what is a member and why would I want to be one?
The one weirdness missing to me is that membership simply says you can merge things, whereas from what you imply, FCPs are also possible as well.
There was a problem hiding this comment.
Added a mention about FCPs in the "What it means to be a mdBook team member" section.
| 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?* |
There was a problem hiding this comment.
| - *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?* |
There was a problem hiding this comment.
| - *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?* |
| 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 |
There was a problem hiding this comment.
nit but I think the team is lowercase
| - 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 |
There was a problem hiding this comment.
outdated
| 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. |
There was a problem hiding this comment.
This seems weird. What does it mean for an FCP to be added to the merge queue. Also are we going to have an RFC process for mdBook?
| - 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) |
There was a problem hiding this comment.
This isn't what majority means, better to just say the criterion and not majority. I think the FCP rules are actually a little more complicated too; there's an exception for small teams like ours (currently). So we should check the full rules.
| 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 |
There was a problem hiding this comment.
| - This is the preferred way. It allows to prevent users to lose too much time implementing | |
| - This is the preferred way. It reduces the risk of contributors losing too much time implementing |
| - Opening a pull request on the [`rust-lang/mdBook`][mdbook] repository is a lightweight | ||
| mechanism suitable for most proposals. |
There was a problem hiding this comment.
This is confusing. It sounds like the PR is for the proposal, when really the PR is for the code and also counts as the proposal.
|
|
||
| ### When are FCPs required? | ||
|
|
||
| An FCP will be needed for any stabilization of user-facing changes, like UI/UX changes, |
There was a problem hiding this comment.
| An FCP will be needed for any stabilization of user-facing changes, like UI/UX changes, | |
| An FCP will be needed for any stabilization of user-facing changes, like major UI/UX changes, |
7 participants
I derived it from the rustdoc team processes minus the things that don't apply (like RFCs, although I kept FCPs).
cc @rust-lang/mdbook
Rendered