Merge pull request #105 from nikomatsakis/initiatives

introduce new lang team "initiatives" process

Author: nikomatsakis

.github/ISSUE_TEMPLATE/active_initiative.md

@@ -0,0 +1,31 @@
+---
+name: Active initiative tracking issue
+about: Issue representing an active initiative
+title: "(My meeting proposal)"
+labels: lang-initiative, T-lang
+assignees: ""
+---
+
+# Summary
+
+_Briefly describe the goal of the initiative_
+
+# Info
+
+- Owner: _name here_
+- Liaison: _name here_
+- Zulip stream [`#project-XXX`](XXX)
+- [stage]: Experimental
+- Repository [rust-lang/XXX](https://github.com/rust-lang/XXX) (if any)
+
+[Stage]
+
+# What is this issue?
+
+This issue represents an **[active initiative]**. It is meant to be used for
+the group to post updates to the lang team (and others) in a lightweight
+fashion. Please do not use the comments here for discussion, that should be kept
+in the Zulip stream (discussion comments here will be marked as off-topic).
+
+[stage]: https://lang-team.rust-lang.org/initiatives/stages.md
+[active initiative]: https://lang-team.rust-lang.org/initiatives.md

.github/ISSUE_TEMPLATE/initiative_proposal.md

@@ -0,0 +1,37 @@
+---
+name: Initiative proposal
+about: Propose a new initiative affiliated with the lang-team
+title: "(My initiative proposal)"
+labels: major-change, T-lang
+assignees: ""
+---
+
+# Proposal
+
+## Summary and problem statement
+
+_Describe the problem(s) this initiative is trying to solve as concisely as you can._
+
+## Motivation, use-cases, and solution sketches
+
+_Please describe the problem you are trying to solve and give some use-cases that illustrate it._
+
+_Please also sketch out one or more solutions to the problem. You don't have to have all the details worked out, but it should be enough to convey the idea._
+
+## Links and related work
+
+_Provide links to any internal thread(s), github issues, related work from other languages, or other things that are worth following up on._
+
+## Initial people involved
+
+- Owner, if known:
+- Liaison
+
+## What happens now?
+
+This issue is part of the lang-team [initiative process]. Once this issue is filed, a Zulip topic will be opened for discussion, and the lang-team will review open proposals in its weekly triage meetings. You should receive feedback within a week or two.
+
+**This issue is not meant to be used for technical discussion. There is a Zulip stream for that. Use this issue to leave procedural comments, such as volunteering to review, indicating that you second the proposal (or third, etc), or raising a concern that you would like to be addressed.**
+
+[forge]: https://forge.rust-lang.org/
+[initiative process]: https://lang-team.rust-lang.org/initiatives.md

.github/ISSUE_TEMPLATE/project-group.md

@@ -13,7 +13,8 @@ rust:
   - stable
 
 before_script:
-  - cargo install --vers "^0.4.5" mdbook
+  - cargo install --vers "^0.4.10" mdbook
+  - cargo install --vers "^0.8.3" mdbook-mermaid
 
 script:
   - mdbook build && mdbook test

.github/ISSUE_TEMPLATE/project_proposal.md

@@ -4,3 +4,20 @@ language = "en"
 multilingual = false
 src = "src"
 title = "The Rust Language Design Team"
+
+[output.html]
+additional-js =["mermaid.min.js", "mermaid-init.js"]
+
+[output.html.fold]
+enable = true
+level = 0
+
+[preprocessor]
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
+
+[output.html.redirect]
+"/rust-2018/edition-changes.html" = "index.html"
+"/priorities.html" = "initiatives/priorities.html"
+"/project_groups.html" = "initiatives/active.html"
+"/proposing_a_project.html" = "initiatives/proposing.html"

.travis.yml

@@ -0,0 +1 @@
+mermaid.initialize({startOnLoad:true});

book.toml

@@ -1,12 +1,27 @@
 # Summary
 
 - [Welcome](./welcome.md)
+- [Initiatives](./initiatives.md)
+  - [Current priorities](./initiatives/priorities.md)
+  - [Process](./initiatives/process.md)
+    - [Roles](./initiatives/process/roles.md)
+      - [Owner](./initiatives/process/roles/owner.md)
+      - [Liaison](./initiatives/process/roles/liaison.md)
+    - [Stages](./initiatives/process/stages.md)
+      - [Proposal](./initiatives/process/stages/proposal.md)
+      - [Experimental](./initiatives/process/stages/experimental.md)
+      - [Development](./initiatives/process/stages/development.md)
+      - [Feature complete](./initiatives/process/stages/feature_complete.md)
+      - [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)
-- [Current priorities](./priorities.md)
-- [Active project groups](./project_groups.md)
-- [Proposing a new project](./proposing_a_project.md)
 - [Design notes](./design_notes.md)
   - [Allowing integer literals like `1` to be inferred to floating point](./design_notes/int_literal_as_float.md)
   - [Generalizing coroutines](./design_notes/general_coroutines.md)

mermaid-init.js

@@ -11,4 +11,3 @@ meetings.
 [caldav]: https://calendar.google.com/calendar/embed?src=recud4b9o8cmc0m5rmr033p5nk%40group.calendar.google.com
 [ics]: https://calendar.google.com/calendar/ical/recud4b9o8cmc0m5rmr033p5nk%40group.calendar.google.com/public/basic.ics
 [main meeting]: https://calendar.google.com/event?action=TEMPLATE&tmeid=NmU4ajUyaWpmaHZic2YzYXVxa25rcnIyZHRfMjAxOTA0MTFUMTkwMDAwWiByZWN1ZDRiOW84Y21jMG01cm1yMDMzcDVua0Bn&tmsrc=recud4b9o8cmc0m5rmr033p5nk%40group.calendar.google.com&scp=ALL
-

mermaid.min.js

@@ -0,0 +1,3 @@
+# Lang team "how to" guide
+
+This section includes instructions on how to do various interactions with the lang team.

src/SUMMARY.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.

src/calendar.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

src/how_to.md

@@ -0,0 +1,3 @@
+# Propose an initiative
+
+See the [initiative process](../initiatives/process.md) for more details.

src/how_to/design_meeting.md

@@ -0,0 +1,33 @@
+# Initiatives
+
+A lang team **initiative** is some active effort with a clear goal or deliverable.
+Typically initiatives are changes to the language, but they could also be documentation, specifications, or something internal to the lang team.
+
+## Proposed initiatives
+
+You can see the [currently proposed initiatives] on Github.
+
+[currently proposed initiatives]: https://github.com/rust-lang/lang-team/issues?q=is%3Aissue+is%3Aopen+label%3Amajor-change
+
+## Active initiatives
+
+You can see the active initiatives, and their state, on the lang team [project board].
+
+[project board]: https://github.com/rust-lang/lang-team/projects/2
+
+### Learning more about an active initiative
+
+Each initiative has a tracking issue that describes its state in more detail along with regular updates. The tracking issue also identifies two key people for the intiative:
+
+- The [owner], who drives the design.
+- The [liaison], who synchronizes with the lang team and helps resolve thorny questions.
+
+If you have questions, the issue also identifies the [Zulip] stream where conversation is taking place. If you look at the comments of the issue, you may also find requests for help or other forms of participation.
+
+[owner]: initiatives/roles/owner.md
+[liaison]: initiatives/roles/liaison.md
+[zulip]: ./chat_platform.md
+
+## How does one propose a new initiative?
+
+Read more in the [process](./initiatives/process.md) page!

src/how_to/nominate.md

@@ -0,0 +1,25 @@
+# "Frequently asked questions" about initiatives
+
+## Does the initiative owner make decisions?
+
+The initiative owner drafts the proposed design and takes feedback from the liaison and team about what direction to take. This feedback can take the form of "you need to do X", but typically it is more about "you need to address this scenario". Or, put another way, if the initiative owner doesn't like the proposed direction, it's up to them to find an alternative that they do like which meets those same constraints, or to argue why the constraints are not necessary.
+
+Note that serving as initiative owner is a high level of responsibility and may not be a good "starting place" for involvement within the Rust project. In practice, initiative owners should be experienced enough that they could mentor others to do the implementation work. If you don't know the language or system well enough to do that, then you probably are not ready to be an owner -- but you may be ready to be mentored by the owner!
+
+## Is the word of a lang team member law?
+
+Of course not. Well, ok, sometimes. For the most part, initiative owners are encouraged to treat lang team members like any other member of the community -- this implies a lot of respect for their opinions, since they are experienced, knowledgeable people, but the initiative owner still ultimately owns the design and should use their own judgement about what things to recommend. However, lang team members do have the option of adding constraints that must be met, and they can override the initiative owner if necessary. That is typically done by raising the concern with the rest of the team/leads in a more formal way.
+
+## 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 "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. 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

src/how_to/propose.md

@@ -0,0 +1,58 @@
+# Process
+
+This page describes how lang team initiatives work. This is the process to use if you have an idea for a change you would like to make in the language.
+
+## Summary
+
+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 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" and its associated page in the [Unstable Book](https://doc.rust-lang.org/nightly/unstable-book/the-unstable-book.html) also incudes a disclaimer that the content has not been RFC'd.
+  - 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" (the unstable book can also be updated).
+  - The goal here is both to implement the feature and to create an "explainer" that guides people on what it does (this can be located in the unstable book or elsewhere).
+- [Feature complete]
+  - When the liaison feels that the code and explainer are ready, the initiative may be declared "feature complete".
+  - This is primarily a 'signaling' mechanism to the broader community 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 can stick around as a place for further discussion, but the initiative is complete. Any Rust team and repository is typically archived.
+  - The final step is to conduct a retrospective discussion between the [owner] and [liaison] about how the process went.
+
+[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
+
+- **Empower individuals and give ownership:**
+  - Each initiative in this proposal is ultimately owned by a single person who drafts the proposals and recommendations.
+  - The role of the lang 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

src/initiatives.md

@@ -0,0 +1,20 @@
+# Roles
+
+There are several key roles for any initiative:
+
+- 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
+
+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