Skip to content

Instantly share code, notes, and snippets.

@nikomatsakis
Last active July 8, 2021 17:07
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save nikomatsakis/5982f618d4dc8321e4e7a1d0b0c180fd to your computer and use it in GitHub Desktop.
Save nikomatsakis/5982f618d4dc8321e4e7a1d0b0c180fd to your computer and use it in GitHub Desktop.
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index 14bc771..07ad652 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -15,6 +15,10 @@
- [Stabilized](./initiatives/process/stages/stabilized.md)
- [Inactive](./initiatives/process/stages/inactive.md)
- [FAQ](./initiatives/faq.md)
+- [Lang team "how to" guide](./how_to.md)
+ - [Nominate an issue](./how_to/nominate.md)
+ - [Propose an initiative](./how_to/propose.md)
+ - [Request a design meeting](./how_to/design_meeting.md)
- [Chat platform](./chat_platform.md)
- [Calendar](./calendar.md)
- [Meetings](./meetings.md)
diff --git a/src/how_to.md b/src/how_to.md
new file mode 100644
index 0000000..695e402
--- /dev/null
+++ b/src/how_to.md
@@ -0,0 +1,3 @@
+# Lang team "how to" guide
+
+This section includes instructions on how to do various interactions with the lang team.
diff --git a/src/how_to/design_meeting.md b/src/how_to/design_meeting.md
new file mode 100644
index 0000000..f0a85d1
--- /dev/null
+++ b/src/how_to/design_meeting.md
@@ -0,0 +1,15 @@
+# Proposing a topic for a design meeting
+
+You can propose a topic for a design meeting by opening an [Design
+meeting proposal] issue on the lang-team repository. We schedule meetings in our monthly
+planning meeting.
+
+[design meeting proposal]: https://github.com/rust-lang/lang-team/issues/new/choose
+
+Every design meeting begins by reading a document and leaving comments. That document
+must be prepared 24 hours in advance of the design meeting and posted on the issue.
+If you propose an issue, you should be willing to prepare that document, or else indicate
+who will do the preparation.
+
+Typically, design meetings are associated with active initiatives: you may wish to
+[propose an initiative](./propose.md) instead.
diff --git a/src/how_to/nominate.md b/src/how_to/nominate.md
new file mode 100644
index 0000000..2607bff
--- /dev/null
+++ b/src/how_to/nominate.md
@@ -0,0 +1,15 @@
+# Nominate an issue
+
+- Nomination is currently supported on the following repositories:
+ - rust-lang/rfcs
+ - rust-lang/rust
+ - rust-lang/reference
+ - rust-lang/lang-team
+ - (this set is defined by the `nominated` list in the [triagebot source code](https://github.com/rust-lang/triagebot/blob/master/src/agenda.rs))
+- Tag the issue with the `I-nominated` and `T-lang` labels by issuing the following [rustbot] command:
+ - `@rustbot label +I-nominate +T-lang`
+- Add a comment explaining
+ - What question you would like answered by the lang team
+ - Relevant background info or links to relevant info that the lang team can use to get "oriented" in the discussion
+
+[rustbot]: https://github.com/rust-lang/triagebot/wiki
diff --git a/src/how_to/propose.md b/src/how_to/propose.md
new file mode 100644
index 0000000..65c1716
--- /dev/null
+++ b/src/how_to/propose.md
@@ -0,0 +1,3 @@
+# Propose an initiative
+
+See the [initiative process](../initiatives/process.md) for more details.
diff --git a/src/initiatives/faq.md b/src/initiatives/faq.md
index 5924256..b67a56d 100644
--- a/src/initiatives/faq.md
+++ b/src/initiatives/faq.md
@@ -12,12 +12,14 @@ Of course not. Well, ok, sometimes. For the most part, initiative owners are enc
## What happens if an owner stops working on things?
-Initiative owners are often volunteers and may have changes in priorities or find they don't have as much time as they thought they did. In that case, they can simply step back. The liaison can then either find a new initiative owner, or perhaps assume initiative owner duties themselves but find a new liaison. If they are not able to do that, the initiative will be closed as "suspended".
+Initiative owners are often volunteers and may have changes in priorities or find they don't have as much time as they thought they did. In that case, they can simply step back. The liaison can then either find a new initiative owner, or perhaps assume initiative owner duties themselves but find a new liaison. If they are not able to do that, the initiative will be closed as "paused".
## What if we decide a initiative is a bad idea?
-Sometimes, in the course of trying to design a initiative, we decide it was the wrong direction. That's ok! At any point the liaison can decide that the initiative isn't working out and close it. However, in doing so, they should document WHY they feel it did not work out -- and identify potential conditions where the idea may make sense later on.
+Sometimes, in the course of trying to design a initiative, we decide it was the wrong direction. That's ok! At any point the liaison can decide that the initiative isn't working out and close it. However, in doing so, they should document WHY they feel it did not work out -- and identify potential conditions where the idea may make sense later on. This documentation will typically take the form of a [design note] in the lang-team repository.
If there are concerns about this, those concerns can be raised with the lang team leads.
Closed initiatives will be removed from the project board and the code for them will be removed from the compiler.
+
+[design note]: ../design_notes.md
diff --git a/src/initiatives/process.md b/src/initiatives/process.md
index f0940e5..c60a43e 100644
--- a/src/initiatives/process.md
+++ b/src/initiatives/process.md
@@ -4,27 +4,38 @@ This page describes how lang team initiatives work. This is the process to use i
## Summary
-The process in a nutshell works like this:
+In a nutshell, the process for a successful initiative is as follows:
- Have an idea
- Talk about it on internals, Zulip, etc to flesh it out a bit
- Ideally, identify a potential [owner]
-- Open a [proposal] as an issue
-- A lang team member can decide to be your [liaison] and [_second_ your proposal][2nd]:
- - Once that happens, you start working towards an RFC, together with the liaison.
- - We will create a Zulip stream for this initiative
- - If needed, you can land experimental code under a feature gate
- - We can also create a repo or a project group, if that's useful
-- You open the RFC.
- - Once RFC is approved, continue development and bring the feature to a final state.
-- Declare the code "feature complete" and seek feedback and testing.
-- Finally, prepare a stabilization report!
+- Open a [proposal] as an issue on the lang-team repository
+ - A lang team member can decide to be your [liaison] and [_second_ your proposal][2nd].
+ - Once that happens, we will create a Zulip stream, tracking issue, and (optionally) repository, etc.
+- If warranted, [explore][experimental] the design space and author the RFC
+ - In this phase, the [owner] works with the [liaison] and other contributors to expore the design space and develop the RFC
+ - Code can be landed in this phase, but the feature gate is marked as "experimental"
+ - Users of the feature gate will get a warning that the RFC is under development
+ - Once the RFC is ready, it can be opened on the RFC repository and approved by the lang team
+- Finish [development]
+ - At this point, development proceeds but the feature gate does not have to be marked as "experimental"
+- [Feature complete]
+ - When the liaison feels that it is ready, the initiative may be declared "feature complete".
+ - This is primarily a 'signaling' mechanism to encourage testing and feedback.
+ - This is a good phase in which to write the Rust reference chapter and other supporting documentation.
+ - Presuming feedback is positive, a stabilization report is prepared and (hopefully) approved.
+- [Stabilized]
+ - Done! The Zulip stream and group can stick around as a place to report bugs or for further discussion, but the initiative is complete.
[proposal]: ./process/stages/proposal.md
[owner]: ./process/roles/owner.md
[liaison]: ./process/roles/liaison.md
[proposal]: ./process/stages/proposal.md
[2nd]: ./process/stages/proposal.html#exit-seconding-a-proposal
+[experimental]: ./process/stages/experimental.md
+[development]: ./process/stages/development.md
+[feature complete]: ./process/stages/feature_complete.md
+[stabilized]: ./process/stages/stabilized.md
## Goals
@@ -32,7 +43,14 @@ The process in a nutshell works like this:
- Each initiative in this proposal is ultimately owned by a single person who drafts the proposals and recommendations.
- The role of team is to review the designs, provide feedback, and ultimately decide whether to accept the design.
- The team can introduce constraints and requests that the owner should either satisfy or explain why they are not able to do so.
+- **Clarify the role of each individual:**
+ - As described in the [roles] page, each individual and group involved in an initiative has a clear, defined role in the decision making process.
- **Minimize friction for "reversible" decisions and enable experimentation:**
- We avoid requiring "full checkoff" from team members for things that can be readily reversed.
- We want to make it relatively easy to start hacking and experimenting with an idea. Under this proposal, all it takes is to find an owner, a liaison, and to have the team leads approve.
- Other team members are encouraged to log concerns and constraints that ought to be addressed in the design, rather than blocking experimentation.
+- **Ensure that decisions are truly reversible:**
+ - On the flip side, although we wish to make it easy for ideas to move forward, we recognize that this can create a lot of momentum that allows ideas to force their way through the process.
+ - This is why code in the [experimental] phase issues a warning, for example.
+
+[roles]: ./process/roles.md
diff --git a/src/initiatives/process/roles.md b/src/initiatives/process/roles.md
index 5d4cec7..7fdccf1 100644
--- a/src/initiatives/process/roles.md
+++ b/src/initiatives/process/roles.md
@@ -1,11 +1,20 @@
# Roles
-There are two key roles for any initiative:
+There are several key roles for any initiative:
-- The [owner], who drives the design.
-- The [liaison], who synchronizes with the lang team and helps resolve thorny questions.
+- The [owner] assembles the "menu" of overall solutions to the problem and helps to narrow them down to the most viable.
+ - Naturally, they are encouraged to make recommendations on what they consider to be the right choice. These recommendations should include an explanation of what analysis they did on the other options that led them to this recommendation.
+- The [liaison] represents the lang team:
+ - They guide the owner in picking from the menu. Naturally they may also make suggestions, ask questions, or request that the owner expand or explore a fresh area.
+ - They identify when to involve the full team via a [design meeting].
+ - They keep up to date on the initiative's progress and can summarize its status for other lang team members.
+- The **lang team members** make the ultimate decision on what changes to accept.
+ - They don't typically do the design, though of course they may make suggestions or introduce constriants that the design ought to meet (the owner can argue that these constraints are undesirable).
+- The **lang team leads** make the ultimate decisions on prioritiziation (which initiatives to pursue).
+ - They also help resolve other disputes that fail to come to agreement
-Each role is played by a single person, though that person can change over time. They cannot both be played by the same person.
+The owner and liaison are each a single person, though that person can change over time. They cannot both be the same person.
[owner]: ./roles/owner.md
[liaison]: ./roles/liaison.md
+[design meeting]: ../../meetings.md
diff --git a/src/initiatives/process/roles/liaison.md b/src/initiatives/process/roles/liaison.md
index 027def2..263a245 100644
--- a/src/initiatives/process/roles/liaison.md
+++ b/src/initiatives/process/roles/liaison.md
@@ -1,6 +1,6 @@
# Initiative liaison
-The **liaison** for an initiative is a "minimally invested" lang team member who is responsible for tracking its progress and giving updates to the lang team. They should also help advise the owner on how to resolve issues and when to seek the feedback of the broader lang team or other stakeholders.
+The **liaison** for an initiative is a lang team member who is responsible for tracking its progress and giving updates to the lang team. They should also help advise the owner on how to resolve issues and when to seek the feedback of the broader lang team or other stakeholders.
The liaison and the owner cannot be the same person.
diff --git a/src/initiatives/process/roles/owner.md b/src/initiatives/process/roles/owner.md
index 6042f5a..fc85391 100644
--- a/src/initiatives/process/roles/owner.md
+++ b/src/initiatives/process/roles/owner.md
@@ -1,6 +1,10 @@
# Initiative owner
-The **owner** of an initiative is the person who is ultimately responsible for its design and implementation. They are driving and managing its overall process from conception to completion, though they may work with others to manage pieces of tha process (for example, the implementation is often done by someone else). Initiative owners do not have to be members of the lang team, but they do have to be sufficiently experienced and dedicated to drive the initiative with minimal assistance. Owning an initiative is also a common stepping stone on the path to full lang team membership.
+The **owner** of an initiative is the person who is ultimately responsible for its design and implementation. They are driving and managing its overall process from conception to completion, though they may work with others to manage pieces of tha process (for example, the implementation is often done by someone else).
+
+The owner is not the decision maker, but they have a huge influence on the design. They assemble the "menu" of overall solutions to the problem and help to narrow the choices down to the ones that are most viable. They are also encouraged to make recommendations on what they consider to be the right choice. These recommendations should include an explanation of what analysis they did on the other options that led them to this recommendation.
+
+Owners do not have to be members of the lang team, but they do have to be sufficiently experienced and dedicated to drive the initiative with minimal assistance. Owning an initiative is also a common stepping stone on the path to full lang team membership.
## Pre-requisites
diff --git a/src/initiatives/process/stages.md b/src/initiatives/process/stages.md
index 2958e9e..fa0a265 100644
--- a/src/initiatives/process/stages.md
+++ b/src/initiatives/process/stages.md
@@ -29,7 +29,7 @@ Initiatives can also become [inactive] for a variety of reasons.
The above process is the ideal, but there are alternative routes that occur in practice for simple initiatives. The most common is one that begins with a PR:
- Implement the idea and open a PR.
-- [Nominate] the PR to the lang team's attention.
+- [Nominate](/how_to/nominate.md) the PR to the lang team's attention.
- The lang team may opt to either approve the PR (skip directly to "feature complete"), assign an owner (skip directly to "development"), or to request a proposal.
## Umbrella initiatives
diff --git a/src/meetings.md b/src/meetings.md
index e9ee6aa..a12506e 100644
--- a/src/meetings.md
+++ b/src/meetings.md
@@ -1,13 +1,13 @@
# Meetings
-The lang team has two standing meetings. The current timing for these
+The lang team has several standing meetings. The current timing for these
can be found on the [lang team calendar](./calendar.html). We
generally record our public meetings and post the recordings in our
[YouTube playlist] (along with automatically created subtitles). We
also publish notes and minutes in written form in this github
repository.
-[YouTube playlist]: https://www.youtube.com/playlist?list=PL85XCvVPmGQg-gYy7R6a_Y91oQLdsbSpa
+[youtube playlist]: https://www.youtube.com/playlist?list=PL85XCvVPmGQg-gYy7R6a_Y91oQLdsbSpa
## Triage meeting
@@ -28,22 +28,29 @@ you leave a comment explaining what kind of feedback you would
like. We try to go over all nominated issues and leave a comment
of some kind in response.
-## Design meeting
+## Planning meeting
-The second weekly meeting is our **design meeting**. The design
-meeting topics are used for in-depth discussions on a particular
-topic, often in connection with an active working group.
+We hold a monthly **planning meeting** in which we do two things:
-### Proposing a topic for a design meeting
+- Updates from [active initiatives](./initiatives.md).
+- Schedule design meetings for the remainder of the month.
-You can propose a topic for a design meeting by opening an [Design
-meeting proposal] issue on the lang-team repository. During our weekly
-triage meetings, we scan open issues to try and decide whether to
-schedule meetings in the upcoming weeks.
+After each planning meeting, we post a blog post to the [Inside Rust](https://blog.rust-lang.org/inside-rust/)
+blog announcing the upcoming meetings and any particularly interesting updates.
+Minutes from the planning meetings are posted in the [design-meeting-minutes][dnm] directory.
-[Design meeting proposal]: https://github.com/rust-lang/lang-team/issues/new/choose
+## Design meeting
+
+We reserve a weekly slot to hold **design meetings**. They are scheduled during
+the planning meeting and hence known in advance. Design
+meeting topics are used for in-depth discussions on a particular
+topic, typically in connection with an [active initiative](./initiatives.md).
-[Design meeting minutes are available in this directory.][dmm]
+Every design meeting begins by reading a document and leaving comments. That document
+must be prepared 24 hours in advance of the design meeting and posted on the issue.
+During the meeting, we append notes and minutes to the end of the document, and
+that combination is posted in [the design-meeting-minutes directory][dnm].
-[dmm]: https://github.com/rust-lang/lang-team/tree/master/design-meeting-minutes
+[dnm]: https://github.com/rust-lang/lang-team/tree/master/design-meeting-minutes
+[Instructions for proposing a design meeting are here.](./how_to/design_meeting.md)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment