From 7c499e2a4ceffedac6972614294bec1ec09bc361 Mon Sep 17 00:00:00 2001 From: Mara Bos Date: Wed, 22 Sep 2021 18:23:35 +0200 Subject: [PATCH 1/7] Add documentation about the libs teams and membership. --- book.toml | 6 ++-- src/SUMMARY.md | 5 +++- src/meetings.md | 21 +++++++++++++ src/membership.md | 35 ++++++++++++++++++++++ src/reviewer-checklist.md | 51 ------------------------------- src/reviewing.md | 36 ++++++++++++++++++++++ src/team.md | 63 +++++++++++++++++++++++++++++++++++++++ 7 files changed, 162 insertions(+), 55 deletions(-) create mode 100644 src/meetings.md create mode 100644 src/membership.md delete mode 100644 src/reviewer-checklist.md create mode 100644 src/reviewing.md create mode 100644 src/team.md diff --git a/book.toml b/book.toml index d7a254f..4699954 100644 --- a/book.toml +++ b/book.toml @@ -7,7 +7,7 @@ multilingual = false src = "./src" [build] -create-missing = false +create-missing = true [rust] edition = "2018" @@ -19,6 +19,6 @@ renderer = ["html"] [output.linkcheck] [output.html] -default-theme = "rust" -git-repository-url = "https://github.com/rust-lang/std-dev-guide" git-repository-icon = "fa-github" +git-repository-url = "https://github.com/rust-lang/std-dev-guide" +edit-url-template = "https://github.com/rust-lang/std-dev-guide/edit/master/{path}" diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 887d410..c48ccf8 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -4,7 +4,10 @@ [Getting started](./getting-started.md) -[Reviewer checklist](./reviewer-checklist.md) +- [The library team](./team.md) + - [Meetings](./meetings.md) + - [Membership](./membership.md) + - [Reviewing](./reviewing.md) --- diff --git a/src/meetings.md b/src/meetings.md new file mode 100644 index 0000000..4156539 --- /dev/null +++ b/src/meetings.md @@ -0,0 +1,21 @@ +# Meetings + +Currently, both the Library Team and the Library API Team have a weekly hour-long meeting. +Both meetings are open to non-members by default, although some might be (partially) private when agenda topics require that. + +The meetings are held as video calls through [Jitsi](https://meet.jit.si/), but everyone is welcome to join without video or even audio. +If you want to participate in meeting discussions through text, you can do so through Jitsi's chat function. + +Meetings and their agendas are announced in the [#t-libs/meetings](https://rust-lang.zulipchat.com/#narrow/stream/259402-t-libs.2Fmeetings) channel on Zulip. + +Agendas are generated by the [`fully-automatic-rust-libs-team-triage-meeting-agenda-generator`](https://github.com/rust-lang/libs-team/tree/main/tools/agenda-generator), +which will include all relevant issues and PRs, such as those tagged with `I-nominated` or `S-waiting-on-team`. + +If you have any specific topics you'd like to have discussed in a meeting, feel free to open an issue on the [`libs-team`](https://github.com/rust-lang/libs-team/) repository +and mark it as `I-nominated` and `T-libs` or `T-libs-api`. Or just leave a message in the Zulip channel. + +All the meetings, including those of the library working groups, can be found on our Google Calendar: + + + +[ICS link](https://calendar.google.com/calendar/ical/9kuu8evq4eh6uacm262k0phri8%40group.calendar.google.com/public/basic.ics) diff --git a/src/membership.md b/src/membership.md new file mode 100644 index 0000000..f7d9c16 --- /dev/null +++ b/src/membership.md @@ -0,0 +1,35 @@ +# Membership + +## Library Contributors + +Membership to Library Contributors can be offered by the Library Team once +a regular contributor has made a number of significant contributions over some period of time, +and has shown to have a good judgement on what changes are acceptable. + +## The Library Team and Library API Team + +The Library Team and Library API Team pick their own members, +although it's expected that new members come from the Library Contributors or another Rust team, +and have already been involved in relevant library work. + +## The process + +In all cases, the process of adding a new members goes as follows: + +1. A member of the Library (API) Team proposes the addition of a contributor on our private mailing list. + This includes proposal includes: + - A short description of what this person has been working on; how they have been contributing. + - A few specific examples of cases where this person clearly communicated their ideas. + - A few specific examples that show this person understands what are and what aren't acceptable changes.\ + Someone who makes significant contributions but usually needs to make large adjustments to their PRs might be a wonderful external contributor, + but might not yet be a good match for membership with review persmissions expecting to judge other contributions. +2. Every single team member is asked for their input. No team member must have any objections. + - Objections are ideally shared with the entire team, but may also be shared privately with the team lead or the moderation team. + - Objections ideally include examples showing behavior not in line with the expectations described under step 1 + (or the code of conduct). +3. The team lead reaches out to the moderation team to ask if they are aware of any objections. +4. Only once the team members and the moderation team agree, the new contributor is invited to join. +5. If the new contributor agrees too, a PR is sent to the `team` repository to add them. +6. A blog post is published in the Internals Blog with a short introduction of the new contributor. + The contents of this post can be based on some of the points brought up in the email from step 1. + The contents are first checked with the new contributor before it is published. diff --git a/src/reviewer-checklist.md b/src/reviewer-checklist.md deleted file mode 100644 index a9192c9..0000000 --- a/src/reviewer-checklist.md +++ /dev/null @@ -1,51 +0,0 @@ -# Reviewer checklist - -**Status:** Stub - -Check the [getting started](./getting-started.md) guide for an introduction to developing in the standard library. - -If you'd like to reassign the PR, you can: - -```ignore -r? @user -``` - -## Before you review - -- [ ] Is this a [stabilization](./feature-lifecycle/stabilization.md) or [deprecation](./feature-lifecycle/deprecation.md)? - - [ ] Make sure there's a completed FCP somewhere for it. - - [ ] Ping `@rust-lang/libs` for input. - -## As you review - -Look out for code considerations: - -- [ ] [Design](./code-considerations/design/summary.md) -- [ ] [Breaking changes](./code-considerations/breaking-changes/summary.md) -- [ ] [Safety and soundness](./code-considerations/safety-and-soundness/summary.md) -- [ ] [Use of unstable language features](./code-considerations/using-unstable-lang/summary.md) -- [ ] [Performance](./code-considerations/performance/summary.md) - -## Before you merge - -- [ ] Is the commit log tidy? Avoid merge commits, these can be squashed down. -- [ ] Can this change be rolled up? -- [ ] Is this a [new unstable feature](./feature-lifecycle/new-unstable-features.md)? - - [ ] Create a [tracking issue](./feature-lifecycle/tracking-issues.md). - - [ ] Update the `#[unstable]` attributes to point to it. - -## When you're ready - -Use [`@bors`](./tools-and-bots/bors.md) to merge the pull request. - -To roll up: - -```ignore -@bors r+ rollup -``` - -or just: - -```ignore -@bors r+ -``` diff --git a/src/reviewing.md b/src/reviewing.md new file mode 100644 index 0000000..169a547 --- /dev/null +++ b/src/reviewing.md @@ -0,0 +1,36 @@ +# Reviewing + +Every member of the Library Team, Library API Team, and Library Contributors has 'r+ rights'. +That is, the ability to approve a PR and instruct [`@bors`](https://bors.rust-lang.org/) +to test and merge it into Rust nightly. + +If you decide to review a PR, thank you! +But please keep in mind: + +- You are always welcome to review any PR, regardless of who it is assigned to. + However, do not approve PRs unless: + - You are confident that nobody else wants to review it first. If you think someone else on the team would be a better person to review it, feel free to reassign it to them. + - You are confident in that part of the code. + - You are confident it will not cause any breakage or regress performance. + - It does not change the public API, including any stable promises we make in documentation, unless there's a finished FCP for the change. + - For unstable API changes/additions, it can be acceptable to skip the RFC process if the design is small and the change is uncontroversial. + Make sure to involve `@rust-lang/libs-api` on such changes. +- Always be polite when reviewing: you are a representative of the Rust project, so it is expected that you will go above and beyond when it comes to the Code of Conduct. + +## High-five rotation + +Some of the members of the team are part of the 'high-five rotation'; +the list from which the high-five bot picks reviewers to assign new PRs to. + +Being a member of one of the teams does not come with the expectation to be on this list. +However, members of this list should be on at least one of the three library teams. + +If the bot assigns you a PR for which you do not have the time or expertise to review it, +feel free to reassign it to someone else. +To assign it to another random person picked from the high-five rotation, +use `r? libs`. + +If you find yourself unable to keep up with reviews, +it might be a good idea to (temporarily) remove yourself from the list. +To add or remove yourself from the list, send a PR to change the +[high-five configuration file](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json). diff --git a/src/team.md b/src/team.md new file mode 100644 index 0000000..4b71424 --- /dev/null +++ b/src/team.md @@ -0,0 +1,63 @@ +# The Library Team + +The Rust standard library and the official `rust-lang` crates are +the responsibility of the Library Team. +The Library team makes sure the libraries are maintained, +PRs get reviewed, and issues get handled in time, +although that does not mean the team members are doing all the work themselves. +Many team members and other contributors are involved in this work, +and the team's main task is to guide and enable that work. + +## The Library API Team + +A very critical aspect of maintaining and evolving the standard library is its stability. +Unlike other crates, we can not release a new major version once in a while for backwards +incompatible changes. Every version of the standard library is semver-compatible +with all previous versions since Rust 1.0. + +This means that we have to be very careful with additions and changes to the public interface. +We can deprecate things if necessary, +but removing items or changing signatures is almost never an option. +As a result, we are very careful with stabilizing additions to the standard library. +Once something is stable, we're basically stuck with it forever. + +To guard the stability and prevent us from adding things we'll regret later, +we have a team that specifically focusses on the public API. +Every RFC and stabilization of a library addition/change goes through a FCP process +in which the members of the Library API Team are asked to sign off on the change. + +The members of this team are not necessarily familiar with the implementation details +of the standard library, but are experienced with API design and understand the details +of breaking changes and how they are avoided. + +## The Library Contributors + +In addition to the two teams above, we also have a the Library Contributors, +which is a somewhat more loosely defined team consisting of those who regularly contribute +or review changes to the standard libraries. + +Many of these contributors have a specific area of expertise, +for example certain data structures or a specific operating system. + +## Team Membership + +The Library Team will privately discuss potential new members for itself and Library Contributors, +and extend an invitation after all members and the moderation team is on board with the potential addition. + +See [Membership](./membership.md) for details. + +### r+ permission + +All members of the Library Team, the Library API Team, and the Library Contributors +can approve any PR, as long as they are confident in their review +and are sure no one else needs to be involved in the review. +See [Reviewing](./reviewing.md) for details. + +### high-five rotation + +Some of the members of the team are part of the 'high-five rotation'; +the list from which the high-five bot picks reviewers to assign new PRs to. + +Being a member of one of the teams does not come with the expectation to be on this list. +However, members of this list should be on at least one of the three library teams. +See [Reviewing](./reviewing.md) for details. From a2f4d46e3b7d6426a43a94341788037cbb87f2d9 Mon Sep 17 00:00:00 2001 From: Mara Bos Date: Sat, 25 Sep 2021 22:17:50 +0200 Subject: [PATCH 2/7] Update src/reviewing.md Co-authored-by: Jane Lusby --- src/reviewing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/reviewing.md b/src/reviewing.md index 169a547..a6a6e46 100644 --- a/src/reviewing.md +++ b/src/reviewing.md @@ -28,7 +28,7 @@ However, members of this list should be on at least one of the three library tea If the bot assigns you a PR for which you do not have the time or expertise to review it, feel free to reassign it to someone else. To assign it to another random person picked from the high-five rotation, -use `r? libs`. +use `r? rust-lang/libs`. If you find yourself unable to keep up with reviews, it might be a good idea to (temporarily) remove yourself from the list. From 9a85a567c51650858884fc744344162b98318728 Mon Sep 17 00:00:00 2001 From: Mara Bos Date: Sat, 25 Sep 2021 22:17:55 +0200 Subject: [PATCH 3/7] Update src/team.md Co-authored-by: Jane Lusby --- src/team.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/team.md b/src/team.md index 4b71424..27f88be 100644 --- a/src/team.md +++ b/src/team.md @@ -22,7 +22,7 @@ As a result, we are very careful with stabilizing additions to the standard libr Once something is stable, we're basically stuck with it forever. To guard the stability and prevent us from adding things we'll regret later, -we have a team that specifically focusses on the public API. +we have a team that specifically focuses on the public API. Every RFC and stabilization of a library addition/change goes through a FCP process in which the members of the Library API Team are asked to sign off on the change. From ecacfde88735df9e092da9440047c10b4e12a49d Mon Sep 17 00:00:00 2001 From: Mara Bos Date: Sat, 25 Sep 2021 22:18:05 +0200 Subject: [PATCH 4/7] Update src/membership.md Co-authored-by: Jane Lusby --- src/membership.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/membership.md b/src/membership.md index f7d9c16..bfde003 100644 --- a/src/membership.md +++ b/src/membership.md @@ -17,7 +17,7 @@ and have already been involved in relevant library work. In all cases, the process of adding a new members goes as follows: 1. A member of the Library (API) Team proposes the addition of a contributor on our private mailing list. - This includes proposal includes: + This proposal includes: - A short description of what this person has been working on; how they have been contributing. - A few specific examples of cases where this person clearly communicated their ideas. - A few specific examples that show this person understands what are and what aren't acceptable changes.\ From 929ec76ca413b2f48c53a19ed1eeaf763ce5e3dd Mon Sep 17 00:00:00 2001 From: Mara Bos Date: Wed, 29 Sep 2021 12:58:35 +0200 Subject: [PATCH 5/7] Typo. Co-authored-by: Josh Stone --- src/membership.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/membership.md b/src/membership.md index bfde003..0c22dea 100644 --- a/src/membership.md +++ b/src/membership.md @@ -22,7 +22,7 @@ In all cases, the process of adding a new members goes as follows: - A few specific examples of cases where this person clearly communicated their ideas. - A few specific examples that show this person understands what are and what aren't acceptable changes.\ Someone who makes significant contributions but usually needs to make large adjustments to their PRs might be a wonderful external contributor, - but might not yet be a good match for membership with review persmissions expecting to judge other contributions. + but might not yet be a good match for membership with review permissions expecting to judge other contributions. 2. Every single team member is asked for their input. No team member must have any objections. - Objections are ideally shared with the entire team, but may also be shared privately with the team lead or the moderation team. - Objections ideally include examples showing behavior not in line with the expectations described under step 1 From 2187a1f263236982566524dc2d5bdec0dca5dd49 Mon Sep 17 00:00:00 2001 From: Mara Bos Date: Wed, 29 Sep 2021 12:58:13 +0200 Subject: [PATCH 6/7] Update wording. --- src/team.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/team.md b/src/team.md index 27f88be..5e01dac 100644 --- a/src/team.md +++ b/src/team.md @@ -49,8 +49,7 @@ See [Membership](./membership.md) for details. ### r+ permission All members of the Library Team, the Library API Team, and the Library Contributors -can approve any PR, as long as they are confident in their review -and are sure no one else needs to be involved in the review. +have the permission to approve PRs, and are expected handle this with care. See [Reviewing](./reviewing.md) for details. ### high-five rotation From 5ae297ef3a30e8f92c630b7589f5cd10781b3636 Mon Sep 17 00:00:00 2001 From: Mara Bos Date: Tue, 26 Oct 2021 13:00:22 +0200 Subject: [PATCH 7/7] Update high-five rotation guideline. --- src/reviewing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/reviewing.md b/src/reviewing.md index a6a6e46..a6535f8 100644 --- a/src/reviewing.md +++ b/src/reviewing.md @@ -30,7 +30,7 @@ feel free to reassign it to someone else. To assign it to another random person picked from the high-five rotation, use `r? rust-lang/libs`. -If you find yourself unable to keep up with reviews, +If you find yourself unable to do any reviews for an extended period of time, it might be a good idea to (temporarily) remove yourself from the list. To add or remove yourself from the list, send a PR to change the [high-five configuration file](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json).