update with input from the WG meeting

Author: japaric

rfcs/0000-teams.md

@@ -17,89 +17,144 @@ This RFC proposes that we:
 
 ## Teams
 
+This section describes the role of the teams and mechanisms for changing their memberships.
+
 ### Role
 
-- The role of a team is to oversee the development of the crates under their purview. With input
-  from stakeholders they set the development roadmap of each crate assigned to them.
+The role of a team is to oversee the development of the crates under their purview. With input from
+stakeholders they set the development roadmap of each crate assigned to them.
 
-- The members of a team are the main reviewers of the crates assigned to the team. Teams are
-  free to add collaborators (reviewers) to the repositories they oversee, and to increase / modify
-  their membership as they see fit.
+The members of a team are the main reviewers of the crates assigned to the team. Teams are free to
+add collaborators (reviewers) to the repositories they oversee, and to increase / modify their
+membership as they see fit.
 
-- The team is in charge of publishing new versions of the crates they oversee to crates.io, and of
-  maintaining the CHANGELOG of the project.
+The team is in charge of publishing new versions of the crates they oversee to crates.io, and of
+maintaining the CHANGELOG of the project.
 
 ### Membership
 
-- For visibility, the membership of each team, along with the set of crates they oversee, will be
-  listed in the README of the rust-embedded/wg (previously known as rust-lang-nursery/embedded-wg)
-  repository.
+For visibility, the membership of each team, along with the set of crates they oversee, will be
+listed in the README of the rust-embedded/wg (previously known as rust-lang-nursery/embedded-wg)
+repository.
+
+#### Adding new members
+
+A person that wants to join a team (the "candidate") will first consult with (part of) the team. The
+team may decide that the candidate participates as a collaborator to one of the repositories
+maintained by the team before they apply for membership. After receiving a soft OK from (part of)
+the team the candidate will send a PR to the rust-embedded/wg repository modifying the README file
+to list themselves as a new member.
+
+The complete team will review the PR and perform one of these 3 actions: approve the PR, abstain
+from reviewing, or raise a concern. When the PR achieves the *majority* of votes (defined below) it
+will be merged and the membership changes will be made effective.
+
+#### Voting majority
+
+Voting majority is defined as having more approvals than abstentions and zero unresolved concerns.
+In the case where there are equal numbers of approvals and abstentions (i.e. the team has an even
+number of members) the WG lead will give the casting vote.
+
+#### Removing members
+
+When (part of) a team wishes to remove one of its member they will make a PR to the
+rust-embedded/wg repository updating the README with the modified membership. The team minus the
+member being removed will vote on the proposal. After voting majority (defined in the previous
+section) has been achieved the PR will be merged and the membership changes will be made effective.
 
-- To expand the membership of a team the candidate will send a PR to the rust-embedded/wg repository
-  modifying the README to add themselves as a new member. The current members of the team will
-  review the PR. If all the members approve the PR will be merged and the membership change will be
-  made effective.
+In the case where the member wishes to retire the procedure is similar. The retiring member will
+make a PR notifying the team (e.g. "cc rust-embedded/$team"). In this case no voting is necessary.
+The PR will be merged and the changes will be made effective.
 
 ### The triage team
 
 A special team named `triage` will be also be created. This team has the *very* important task of
 keeping the PR queues moving and making sure no PR gets stuck in the review limbo.
 
-- This team will consist of volunteers that will triage open PRs to rust-embedded repos on a weekly
-  basis.
+This team will consist of volunteers that will triage open PRs to rust-embedded repos on a weekly
+basis. When triaging the members of the `triage` team will assign or change reviewers, add or change
+the labels of the PR, and/or comment on the PRs; they will not review PRs while triaging.
 
-- The `triage` team can't review PRs; they can only change the labels of the PR and comment on the
-  PRs.
+#### The triaging process
 
-- The `triage` team will follow the triage process used in [the rust-lang/rust repo]:
-  - Open PRs will get assigned one of these status label: `S-waiting-on-author` or
+The proposed triaging process is based on [the one used in the rust-lang/rust repo][rust-triage].
+
+[rust-triage]: https://github.com/rust-lang/rust/pulls
+
+- Open PRs will get assigned one of these status label: `S-waiting-on-author` or
   `S-waiting-on-reviewer`.
-  - If the PR has no assigned reviewer assign a reviewer and set the `S-waiting-on-reviewer` label.
-  - If around a week has passed since a reviewer was assigned ping the reviewer to remind them about
-    the PR.
-  - If the reviewer requested changes to the PR apply the `S-waiting-on-author` label.
-  - If around a week has passed since changes were requested ping the author to remind them that
-    changes are needed.
-  - If the author made the requested changes change the label to `S-waiting-on-reviewer`.
-  - If the author hasn't responded to pings for over two weeks, close the PR.
 
-[the rust-lang/rust repo]: https://github.com/rust-lang/rust/pulls
+- If the PR has no assigned reviewer assign a reviewer and set the `S-waiting-on-reviewer` label.
+
+- If around a week has passed since a reviewer was assigned ping the reviewer to remind them about
+  the PR.
+
+- If the reviewer requested changes to the PR apply the `S-waiting-on-author` label.
+
+- If around a week has passed since changes were requested ping the author to remind them that
+  changes are needed.
+
+- If the author made the requested changes change the label to `S-waiting-on-reviewer`.
+
+- If the author hasn't responded to pings for over two weeks, close the PR.
+
+## Projects
 
-## Crate inclusion policy
+The section describes the guideline for incorporating projects into the rust-embedded organization
+and the mechanism for adopting projects.
 
-Only crates that are widely used and / or that have a wide scope will be maintained by the
-embedded-rust org. Additionally, the crate must compile on stable Rust 1.31. In principle, this
-excludes HAL implementations crate like the [`stm32f103xx-hal`] but exception can be made for crates
-with narrow scope, like the [`f3`] crate, that are used by widely used resources like the
-[`discovery`] book.
+### Inclusion guideline
+
+Only projects (crates or documentation) that are widely used and / or that have a wide scope will be
+maintained by the embedded-rust org. Additionally, if the project is a crate it must compile on the
+stable channel by Rust 1.31 (2018-12-06); if the project is documentation all the included code and
+patterns must be usable on the stable channel.
+
+In principle, this guideline excludes HAL implementation crates like the [`stm32f103xx-hal`] and
+board support crates because of their narrow scope but exceptions could be made for crates, like the
+[`f3`] crate, that are dependencies of widely used resources like the [`discovery`] book.
 
 [`stm32f103xx-hal`]: https://github.com/japaric/stm32f103xx-hal
+[`f3`]: https://github.com/japaric/f3
+[`discovery`]: https://github.com/japaric/discovery
+
+### Adopting projects
+
+An author that wishes to have their project adopted by the rust-embedded org should first approach
+the team that would oversee their crate if it were to be adopted. If the author is unsure which team
+should take ownership of their project they will first open an issue in the rust-embedded/wg
+repository requesting input.
+
+After getting a soft OK from (part of) the team the author will send a PR to rust-embedded/wg adding
+their repository to the list of crates the team maintains. After voting majority (see definition in
+the membership section) the PR will be merged, ownership will be transferred and the author will
+become a collaborator of the transferred repository.
 
-The procedure to add a crate is similar to the one used to add a new member to a team. The author
-of the crate will make a PR modifying the README of the rust-embedded/wg repo. The team that
-will adopt the crate will review the PR. If everyone accepts, the PR will be merged, the author will
-transfer ownership of the repo to the org, and the author will become a collaborator.
+## Guidelines
 
-## Reviewing guidelines
+This section contains a set of guidelines that aim to standardize the management of projects
+within the rust-embedded org.
+
+### Reviewing
 
 - The `master` branches will be protected and can't be directly pushed to.
 
-- All changes will go through a PR, which must pass review and [bors] before landing. A team member
-  / collaborator can't review / approve their own PR.
+- All changes will go through a PR that must pass review and [bors] before landing. Team members
+  and collaborators can't approve their own PRs.
 
 [bors]: https://bors.tech
 
 - Breaking and major changes must be consulted with other team members, reviewers and stakeholders
-  before the PR is reviewed. A mini [RFC] must be written listing the rationale of the change and
-  the alternatives.
+  before the PR is reviewed. The team will decide whether a mini [RFC], listing the rationale of the
+  change and the alternatives, needs to be written.
 
 [RFC]: https://github.com/rust-lang/rfcs#table-of-contents
 
 - Mandatory: Read the [Rust API guidelines] before you start reviewing PRs that add new API.
 
 [Rust API guidelines]: https://rust-lang-nursery.github.io/api-guidelines/about.html
 
-## Publishing guidelines
+### Publishing
 
 - Publish patch releases (bug fixes) often.
 
@@ -112,17 +167,17 @@ transfer ownership of the repo to the org, and the author will become a collabor
 
 [semver-trick]: https://github.com/dtolnay/semver-trick
 
-## Repository guidelines
+### Repository contents
 
 - The README of all repositories will indicate which team is in charge of the repository and it will
-  link to the teams sections of the README of the rust-embedded/wg repo.
+  link to the teams section of the README in the rust-embedded/wg repo.
 
 - All the repositories that are crates will maintain a CHANGELOG.md file that adheres to the [keep a
   changelog] format.
 
 [keep a changelog]: https://keepachangelog.com/en/1.0.0/
 
-- The repository will include a copy of Rust [Code of Conduct]. Each team will enforce the code of
+- The repository will include a copy of Rust's [Code of Conduct]. Each team will enforce the code of
   conduct in the repositories they govern.
 
 [Code of Conduct]: https://github.com/rust-lang/rust/blob/master/CODE_OF_CONDUCT.md
@@ -132,29 +187,19 @@ transfer ownership of the repo to the org, and the author will become a collabor
 
 ## Other changes
 
-- `rust-lang-nursery/embedded-wg` -> `rust-embedded/wg`
+- Transfer the `rust-lang-nursery/embedded-wg` to the rust-embedded org and rename it to
+  `rust-embedded/wg`.
+
 - The embedded Rust book and the embedonomicon which currently live in `rust-embedded/wg` will be
   moved into their own repositories.
+
 - The newletters in `rust-embedded/wg` will also be moved into their own repository.
-- The logo of the rust-embedded logo will change to the embedded WG logo.
+
+- The logo of the rust-embedded org will change to the embedded WG logo.
+
 - All members of the rust-embedded org will be able to manage issues and PRs in the rust-embedded/wg
   repository.
 
 # Alternatives
 
 An alternative to this proposal is to have the architectures teams be their own independent orgs.
-
-# Unresolved questions
-
-> Where is the AVR team?
-
-Only architectures with built-in support, or that will soon have built-in support, in `rustc` have
-been considered in this proposal. We can spin up more teams in the future.
-
-- Should we require that would-be team members do some time as collaborators before they apply?
-
-- The procedure for having a team member retire is still TBD.
-
-- The procedure for removing (deprecating?) a crate from the rust-embedded org is still TBD.
-
-- The procedure for creating a brand new team is still TBD.