Carbon: Proposal tracking

docs/project/commenting_guidelines.md

@@ -19,10 +19,10 @@ always try to keep feedback, even when critical, constructive and supportive.
 
   - Objections to specific phrasing should suggest alternative phrasing.
 
-- **Use Discourse Forums for long comments.** If a Google Doc comment would be
-  over two paragraphs, take it to the Discourse Forum topic. Doc comments are
-  good for quick, short feedback; detailed feedback is better shared on
-  Discourse Forums.
+- **Use Discourse Forums for long comments.** GitHub is good for
+  short-to-moderate-sized comments. Discourse Forums is better for long,
+  detailed comments, particularly where multiple parties may get involved in
+  discussion.
 
   - Use the forum topic created by the author, rather than creating a new topic.
     It needs to be easy for authors and other reviewers to find comments.

docs/project/consensus_decision_making.md

@@ -103,9 +103,9 @@ items, meetings will not be held.
 Agenda items (e.g., proposals) should be added at least one week in advance (or
 four working days, if longer), so that members have time to review items added
 to the agenda. Sub-items (e.g., proposal discussion points) should be added at
-least one day before the meeting; every open Google Doc comment is implicitly a
-sub-item. Please feel free to add items to the agenda and remove them later if
-the agenda item is resolved over other communication forums.
+least one day before the meeting; every open GitHub pull request comment is
+implicitly a sub-item. Please feel free to add items to the agenda and remove
+them later if the agenda item is resolved over other communication forums.
 
 Team members are expected to prepare for the meeting by ensuring they're
 familiar with the proposal and related discussion. The meeting will not include

docs/project/evolution.md

@@ -37,51 +37,53 @@ guidelines for
 
 The process is:
 
-1.  [Draft the proposal](#draft-the-proposal)
+1. [Draft the proposal](#draft-the-proposal)
 
-    1.  [(optional) Discuss the idea early](#optional-discuss-the-idea-early)
-    2.  [Make a proposal](#make-a-proposal)
-    3.  [(optional) Elicit early, high-level feedback on the proposal](#optional-elicit-early_high_level-feedback-on-the-proposal)
+   1. [(optional) Discuss the idea early](#optional-discuss-the-idea-early)
+   2. [Make a proposal](#make-a-proposal)
+   3. [(optional) Elicit early, high-level feedback on the proposal](#optional-elicit-early_high_level-feedback-on-the-proposal)
 
-2.  [Solicit and address proposal feedback](#solicit-and-address-proposal-feedback)
+2. [Solicit and address proposal feedback](#solicit-and-address-proposal-feedback)
 
-    1.  [Request comments](#request-comments)
-    2.  [Community and reviewing team comments on proposal](#community-and-reviewing-team-comments-on-proposal)
-    3.  [(optional) Pause for a major revision](#optional-pause-for-a-major-revision)
-    4.  [Request a review manager](#request-a-review-manager)
+   1. [Request comments](#request-comments)
+   2. [Community and reviewing team comments on proposal](#community-and-reviewing-team-comments-on-proposal)
+   3. [(optional) Pause for a major revision](#optional-pause-for-a-major-revision)
+   4. [Request a review manager](#request-a-review-manager)
 
-3.  [Reviewing team makes a proposal decision](#reviewing-team-makes-a-proposal-decision)
+3. [Reviewing team makes a proposal decision](#reviewing-team-makes-a-proposal-decision)
 
-    1.  [Prepare the document for a proposal decision](#prepare-the-document-for-a-proposal-decision)
-    2.  [Ask the reviewing team for a proposal decision](#ask-the-reviewing-team-for-a-proposal-decision)
-    3.  [(optional) Use the meeting to make a proposal decision](#optional-use-the-meeting-to-make-a-proposal-decision)
+   1. [Prepare the document for a proposal decision](#prepare-the-document-for-a-proposal-decision)
+   2. [Ask the reviewing team for a proposal decision](#ask-the-reviewing-team-for-a-proposal-decision)
+   3. [(optional) Use the meeting to make a proposal decision](#optional-use-the-meeting-to-make-a-proposal-decision)
 
-4.  [Finalize the proposal decision](#finalize-the-proposal-decision)
+4. [Finalize the proposal decision](#finalize-the-proposal-decision)
 
-    1.  [Publish the proposal decision](#publish-the-proposal-decision)
-    2.  [Community comments on proposal decision](#community-comments-on-proposal-decision)
-    3.  [(optional) Rollback the decision](#optional-rollback-the-decision)
-    4.  [Execute on proposal decision](#execute-on-proposal-decision)
+   1. [Publish the proposal decision](#publish-the-proposal-decision)
+   2. [Community comments on proposal decision](#community-comments-on-proposal-decision)
+   3. [(optional) Rollback the decision](#optional-rollback-the-decision)
+   4. [Execute on proposal decision](#execute-on-proposal-decision)
 
 ## Coordination Tools
 
 We use several tools to coordinate changes to Carbon:
 
+- **GitHub pull requests** contain the actual proposal. Resolved proposals will
+  be committed with the associated decision.
+- **GitHub issues** track the proposal process and life cycle. These are only
+  used to track the process, and should not be used for discussion. All GitHub
+  pull requests, Google Docs, and Discourse Forum topics should be linked from
+  the issue for easy indexing.
 - **Discourse Forum** topics will be used for the early idea discussion, any
   deeper discussions, or more high-level and meta points.
 - **Discord Chat** can be used for quick and real-time chats and Q&A.
   - If there are important technical points raised or addressed, they should get
     summarized on a relevant Discourse Forum topic.
-- **Google Docs** is used for writing and reviewing proposals. This facilitates
-  collaborative editing and easy commenting about wording issues.
 - **Google Hangouts Meet** will be used for VC meetings, typically for
   decisions.
   - Meetings should typically be summarized on a relevant Discourse Forum topic.
 - **Google Calendar** will be used to track team meeting and vacation times.
-- **GitHub issues** track the proposal process and life cycle. These are only
-  used to track the process, and should not be used for discussion. All Google
-  Docs and Discourse Forum topics should be linked from the issue for easy
-  indexing.
+- **Google Docs** may be used for early draft proposals. This facilitates
+  collaborative editing and easy commenting about wording issues.
 
 ## Governance structure
 
@@ -241,8 +243,7 @@ efficient.
 
 #### Make a proposal
 
-The first part of making a proposal is to write up a Google Doc explaining,
-roughly in the following order:
+Start by creating a markdown proposal covering (roughly in order):
 
 - **Problem**: Information about the problem the proposal is trying to solve.
 - **Background**: Background on the problem and information needed to understand
@@ -253,24 +254,26 @@ roughly in the following order:
   considered and rejected.
 
 We use a
-[template for proposals](https://docs.google.com/document/d/1sqEnIWWZKTrtMz2XgD7_RqvogwbI0tBQjAZIvOabQsw/template/preview)
-to make it easier for readers to recognize the style and structure. If you
-already have a non-templated Doc, create a Doc using the template and copy
-content over (without the original formatting) so that things like the license
-header are present.
-
-Also create
-[the initial GitHub tracking issue](https://github.com/carbon-language/carbon-proposals/issues/new?template=proposal.md).
-Don't worry about whether the proposal will go anywhere; issues are cheap.
-GitHub issues are expected to be used as an index of different in-flight
-proposals, and may be helpful when trying to find others with similar ideas.
+[template for proposals](https://github.com/carbon-language/carbon-lang/blob/master/proposals/templates.md).
+Please use this to include structure and license information. Follow the
+instructions under "TODO: Initial proposal setup".
+
+Please always create the GitHub tracking issue early. Don't worry about whether
+the proposal will go anywhere; issues are cheap. GitHub issues are expected to
+be used as an index of different in-flight proposals, and may be helpful when
+trying to find others with similar ideas.
 
 When writing a proposal, try to keep it brief and focused to maximize the
 community's engagement in it. Beyond the above structure, try to use
 [Inverted Pyramid](<https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism)>)
 or [BLUF](<https://en.wikipedia.org/wiki/BLUF_(communication)>) writing style to
 help readers rapidly skim the material.
 
+The proposal's pull request may include changes in the same repo. Please be
+thoughtful about how much effort you invest this way: it can help illustrate the
+intent of a proposal and avoid duplicating text in the proposal, but proposals
+may also need to be rewritten substantially or be deferred/declined.
+
 Where parts of a proposal may have several ways to address them, feel free to
 list options and mark them as "open questions". When describing an open
 question, it is a good idea to describe a proposed solution as well as other
@@ -281,20 +284,35 @@ reviewing team.
 Where the proposal makes a decision between multiple options, move them to the
 "alternatives" section so that it's clear why a given choice was made.
 
+##### Drafting using Google Docs
+
+You may optionally use the
+[Google Docs template](https://docs.google.com/document/d/1sqEnIWWZKTrtMz2XgD7_RqvogwbI0tBQjAZIvOabQsw/template/preview)
+for early proposal versions, which can be transferred to Markdown later. Using
+Google Docs can especially help iterate on a propsal with multiple authors.
+
+This template includes things like license headers and standard formatting. If
+you already have a non-templated Doc, please create a new Doc using the template
+and copy content over (without original formatting).
+
+If you use Google Docs for drafting, be sure to still use a Markdown pull
+request for the RFC.
+
 ##### Actions
 
 - **Author**:
   - Write the proposal using
-    [the template](https://docs.google.com/document/d/1sqEnIWWZKTrtMz2XgD7_RqvogwbI0tBQjAZIvOabQsw/template/preview).
-    - The template has additional items under "TODO: Initial proposal setup".
-    - Note that Google Doc and GitHub issue templates have the status set to
+    [the template](https://github.com/carbon-language/carbon-lang/blob/master/proposals/templates.md).
+    - The template has additional instructions under "TODO: Initial proposal
+      setup".
+    - Note that proposal and GitHub issue templates have the status set to
       `WIP`.
 
 #### (optional) Elicit early, high-level feedback on the proposal
 
 Authors may continue to use the `Evolution > Ideas` forum topic to advertise the
 proposal and elicit early, high-level feedback. Community commenters should
-favor the forum topic (vs Doc comments) for high-level discussion.
+favor the forum topic (vs GitHub comments) for high-level discussion.
 
 ##### Actions
 
@@ -310,18 +328,18 @@ favor the forum topic (vs Doc comments) for high-level discussion.
 
 Once authors feel the proposal is in good shape for wider evaluation from the
 relevant reviewing team (the core team, at present), they begin the more formal
-process of evaluation by creating an `Evolution > Proposal Reviews` forum topic
-for technical review of the proposal.
+process of evaluation by creating an `Evolution > RFCs` forum topic for
+technical review of the proposal.
 
 The topic should start off with a brief summary of the proposal and any prior
 discussion, as well as links to prior discussion topics.
 
 ##### Actions
 
 - **Author**:
-  - Set both the Google Doc status and GitHub issue status label to `RFC`.
-  - Create an `Evolution > RFC` forum topic.
-    - Summarize the discussion points, along with a link to the Google Doc and
+  - Set both the proposal status and GitHub issue status label to `RFC`.
+  - Create an `Evolution > RFCs` forum topic.
+    - Summarize the discussion points, along with a link to the pull request and
       GitHub issue.
     - Add the topic's link to the GitHub issue.
 
@@ -346,7 +364,7 @@ also be added where the author isn't confident about the best approach.
 ##### Actions
 
 - **Author**:
-  - Update the Doc and/or comment in the topic to address feedback.
+  - Update the pull request and/or comment in the topic to address feedback.
   - Create GitHub issues for any open questions to be revisited later.
 - **Reviewing team and community**: Provide
   [constructive commentary](commenting_guidelines.md) for proposals.
@@ -369,7 +387,7 @@ discussion points thus far (with links to those prior topics).
 - **Author**:
   - Announce to the Discourse Forum topic that the proposal is undergoing major
     revision.
-  - Set both the Google Doc status and GitHub issue status label to `WIP`.
+  - Set both the proposal status and GitHub issue status label to `WIP`.
 - **Reviewing team and community**: Refrain from commenting until the author
   solicits feedback again.
 
@@ -394,34 +412,26 @@ the reviewing team will be asked to start making a decision after a day.
 - **Author**:
   - Ensure all comments are resolved.
   - Create a `Evolution > Review manager requests` topic asking for a review
-    manager, providing a link to the proposal's Doc and GitHub issue.
+    manager, providing a link to the proposal's pull request and GitHub issue.
     - Add the topic's link to the GitHub issue.
 - **Review manager**:
   - Ask reviewing team members to review the proposal when needed.
   - Double-check that comment threads are addressed by the proposal.
-  - Update the `Evolution > RFC` topic with a last call for comments.
+  - Update the `Evolution > RFCs` topic with a last call for comments.
 
 ### Reviewing team makes a proposal decision
 
 #### Prepare the document for a proposal decision
 
 Going into a decision, it's expected that no more significant changes will be
-made. The review manager should ask the proposal author to transfer ownership of
-the proposal's Doc to the review manager. The review manager should then change
-all "edit" access to "comment".
-
-For the rest of the review, the review manager should reject all non-typo
-suggestions to the proposal. Although the author should continue to respond to
-reviewing team comments, if any significant changes need to be made, the
-decision should be cancelled and the proposal should be returned to the author
-for major revision.
+made. The proposal author should stop making any non-typo edits to the text. Any
+significant edit will be treated as a major revision, cancelling the decision
+request. The author should still respond to review comments, just without
+making/accepting edits.
 
 ##### Actions
 
-- **Author**:
-  [Transfer ownership](https://support.google.com/docs/answer/2494892) of the
-  proposal's Doc to the review manager.
-- **Review manager**: Change all edit access on the proposal to comment-only.
+- **Author**: Stop making changes to the proposal.
 
 #### Ask the reviewing team for a proposal decision
 
@@ -438,7 +448,7 @@ discussion. Try to respond to the Discourse Forum topic promptly with:
 - A position (either affirming or objecting) is strongly preferred, although
   standing aside is allowed.
   - Rationales for positions should be based on discussion on the proposal's
-    `Evolution > RFC` topic, and providing links helps write the decision.
+    `Evolution > RFCs` topic, and providing links helps write the decision.
 - A request for more time to review materials, to make it clear the intent is to
   participate in the decision.
 - Discussion regarding positions or the decision itself.
@@ -447,7 +457,7 @@ discussion. Try to respond to the Discourse Forum topic promptly with:
     to requesting a decision.
 - A request to use the meeting for discussion.
   - All topics for discussion will be captured either in the agenda or as a
-    comment on the Doc, to ensure they're ready for the meeting.
+    comment on the pull request, to ensure they're ready for the meeting.
 
 The review manager should monitor the forum topic for consensus. If a decision
 is made before the meeting, the item should be removed from the meeting agenda.
@@ -459,9 +469,8 @@ make decisions.
 - **Author**:
   - Respond to comments.
 - **Review manager:**
-  - Set both the Google Doc status and GitHub issue status label to
+  - Set both the proposal status and GitHub issue status label to
     `needs decision`.
-    - In the Doc history, label the latest revision as `needs decision`
   - Create an `Evolution > Proposal decisions` topic for pre-meeting discussion.
   - Tentatively add the decision to the meeting one week in advance (or four
     working days, if longer), and use that meeting if necessary to reach
@@ -517,24 +526,30 @@ author again. It's not necessary to switch ownership back.
 
 ##### Actions
 
-- **Review manager**:
+- **Author**:
   - If the proposal needs more changes:
-    - Grant the author edit access to the Doc again.
-    - Set both the Google Doc status and GitHub issue status label to `WIP`.
-  - If the proposal is done changing:
-    - Set both the Google Doc status and GitHub issue status label to
+    - Set both the proposal status and GitHub issue status label to `WIP`.
+  - If the proposal is deferred or declined:
+    - Set both the proposal status and GitHub issue status label to
       `<decision>`.
-  - In the Doc history, label the latest revision as `<decision>`.
+    - Close the pull request, if appropriate.
+  - If the proposal is accepted:
+    - Set both the proposal status and GitHub issue status label to `accepted`.
+    - When the proposal is approved by the reviewing team, commit it.
+      - Add a link to the committed version to the GitHub issue.
+- **Review manager**:
   - Write the
     [formal decision](consensus_decision_making.md#formal-decision-content),
     possibly with help from the reviewing team.
+    - Formal decisions are stored at `/proposals/p####-decision.md`.
     - (optional): Create a GitHub issue for issues that should be revisited in
       the future. Link to these from the main GitHub issue.
   - Create an `Evolution > Announcements` forum topic with the decision and a
     summary of the rationale.
     - Add the topic's link to the GitHub issue.
-- **Reviewing team**: Help draft any rationale needed by the review manager for
-  the decision.
+- **Reviewing team**:
+  - Approve the proposal.
+  - Help draft any rationale needed by the review manager for the decision.
 
 #### Community comments on proposal decision
 
@@ -582,7 +597,8 @@ should be exceptional.
 
 ##### Actions
 
-- **Author**: Roll back any dependent changes.
+- **Author**:
+  - Roll back the committed proposal and any dependent changes.
 - **Reviewing team member**: State new, non-consensus position on
   `Evolution > Decisions` forum topic.
 - **Review manager**: Return to
@@ -610,9 +626,8 @@ revisit the decision.
 ##### Actions
 
 - **Review manager**:
-  - Commit the proposal PDF to the GitHub decision repository.
-    - Once committed, add a link to the PDF in the GitHub issue.
-  - Move the Doc to the archive folder.
+  - Commit the proposal decision.
+    - Add a link to the committed version to the GitHub issue.
   - Update the `Evolution > Announcements` forum topic with the final decision.
   - Close the GitHub issue.
 - **Author**: Start making dependent changes to apply the proposal.

proposals/README.md

@@ -0,0 +1,4 @@
+This directory contains all proposals for the carbon-lang repo. Files will be
+named `p####.md`, where `####` is the corresponding tracking issue. They may
+have associated subdirectories named `p####` which contain related files (e.g.,
+images) for the proposal.