|
|
@@ -1,4 +1,4 @@
|
|
|
-# Governance and evolution
|
|
|
+# Evolution and governance
|
|
|
|
|
|
<!--
|
|
|
Part of the Carbon Language project, under the Apache License v2.0 with LLVM
|
|
|
@@ -6,618 +6,463 @@ Exceptions. See /LICENSE for license information.
|
|
|
SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
|
|
|
-->
|
|
|
|
|
|
-The Carbon project aims to provide consistent and clear governance and language
|
|
|
-evolution over time. We want to provide a reasonably broad representation for
|
|
|
-the community contributing to Carbon, including their diverse backgrounds and
|
|
|
-expertise. The governance also needs to remain scalable and effective. It is
|
|
|
-essential to be able to make even controversial decisions in a reasonable and
|
|
|
-bounded timeframe.
|
|
|
+<!-- toc -->
|
|
|
|
|
|
-## Governance structure
|
|
|
+## Table of contents
|
|
|
+
|
|
|
+- [Overview](#overview)
|
|
|
+- [Proposals](#proposals)
|
|
|
+ - [Life of a proposal](#life-of-a-proposal)
|
|
|
+ - [Proposal roles](#proposal-roles)
|
|
|
+ - [Proposal authors](#proposal-authors)
|
|
|
+ - [Community](#community)
|
|
|
+ - [Active contributors](#active-contributors)
|
|
|
+ - [Carbon leads](#carbon-leads)
|
|
|
+ - [When to write a proposal](#when-to-write-a-proposal)
|
|
|
+ - [Proposal PRs](#proposal-prs)
|
|
|
+ - [Open questions](#open-questions)
|
|
|
+ - [Review and RFC on proposal PRs](#review-and-rfc-on-proposal-prs)
|
|
|
+ - [Blocking issues](#blocking-issues)
|
|
|
+ - [Discussion on blocking issues](#discussion-on-blocking-issues)
|
|
|
+- [Governance structure](#governance-structure)
|
|
|
+ - [Carbon leads](#carbon-leads-1)
|
|
|
+ - [Subteams](#subteams)
|
|
|
+ - [Painter](#painter)
|
|
|
+ - [Adding and removing governance members](#adding-and-removing-governance-members)
|
|
|
+- [Acknowledgements](#acknowledgements)
|
|
|
|
|
|
-Our governance structure supports
|
|
|
-[consensus decision-making](consensus_decision_making.md):
|
|
|
+<!-- tocstop -->
|
|
|
|
|
|
-- Community members write proposals.
|
|
|
-- [Review managers](#review-managers) escort proposals through our consensus
|
|
|
- decision process.
|
|
|
-- A [core team](#core-team) makes consensus decisions about Carbon's
|
|
|
- evolution.
|
|
|
-- Three [arbiters](#arbiters) respond to escalations about lack of consensus,
|
|
|
- making decisions through majority vote.
|
|
|
-- One [painter](#painter) who, where a consensus exists that multiple
|
|
|
- competing options are reasonable, decides between the provided options.
|
|
|
+## Overview
|
|
|
|
|
|
-## Evolution process
|
|
|
+Carbon's evolution process uses [proposals](#proposals) to evaluate and approve
|
|
|
+significant changes to the project or language. The goal is to ensure these
|
|
|
+kinds of changes can receive feedback from the entire community, and also to
|
|
|
+resolve questions and decide direction efficiently. We use proposals to create a
|
|
|
+clear log of rationale for why the project and language have evolved in
|
|
|
+particular directions.
|
|
|
|
|
|
-Any substantive change to Carbon -- whether the language, project,
|
|
|
-infrastructure, or otherwise -- must be made through a process designed to both
|
|
|
-engage with the broader community and come to reasonable decisions in a timely
|
|
|
-fashion. We have guidelines for
|
|
|
-[when to follow the evolution process](#when-to-follow-the-evolution-process).
|
|
|
+When there are questions, concerns, or issues with a proposal that need to be
|
|
|
+resolved, Carbon uses its [governance](#governance-structure) system of
|
|
|
+[Carbon leads](#carbon-leads-1) to decide how to move forward. Leads are
|
|
|
+fundamentally responsible for encouraging Carbon's ongoing and healthy evolution
|
|
|
+and so also take on the critical steps of the evolution process for proposals.
|
|
|
|
|
|
-The process is:
|
|
|
+## Proposals
|
|
|
|
|
|
-1. [Draft the proposal](#draft-the-proposal)
|
|
|
+These are primarily structured as GitHub pull requests that use a somewhat more
|
|
|
+formal document structure and process to ensure changes to the project or
|
|
|
+language are well explained, justified, and reviewed by the community.
|
|
|
|
|
|
- 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)
|
|
|
+### Life of a proposal
|
|
|
|
|
|
-2. [Solicit and address proposal feedback](#solicit-and-address-proposal-feedback)
|
|
|
+- We author and review proposals when making
|
|
|
+ [substantive changes to Carbon](#when-to-write-a-proposal).
|
|
|
|
|
|
- 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)
|
|
|
+- Proposals consist of a PR (pull request) in GitHub that adds a document to
|
|
|
+ the [`proposals/` directory](/proposals/) following
|
|
|
+ [the template](/proposals/template.md).
|
|
|
|
|
|
-3. [Reviewing team makes a proposal decision](#reviewing-team-makes-a-proposal-decision)
|
|
|
+- Proposal PRs start out in draft mode. When proposal PRs are ready, click on
|
|
|
+ ["Ready for review"](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/changing-the-stage-of-a-pull-request#marking-a-pull-request-as-ready-for-review)
|
|
|
+ in GitHub.
|
|
|
|
|
|
- 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)
|
|
|
+ - This will result in a Carbon lead being assigned to review the PR.
|
|
|
|
|
|
-4. [Finalize the proposal decision](#finalize-the-proposal-decision)
|
|
|
+ - This also signifies an RFC (request for comment) from the entire
|
|
|
+ community.
|
|
|
|
|
|
- 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)
|
|
|
+- Contributors should react with a _thumbs-up_ to the proposal PR if they are
|
|
|
+ generally interested and supportive of the high level direction based on
|
|
|
+ title and summary.
|
|
|
|
|
|
-## Coordination tools
|
|
|
+- We use GitHub issues to discuss and track _blocking issues_ with proposals,
|
|
|
+ such as open questions or alternative approaches that may need further
|
|
|
+ consideration. These are assigned to carbon-leads to decide.
|
|
|
|
|
|
-We use several tools to coordinate changes to Carbon:
|
|
|
+- The lead assigned to review the PR should ensure that at least three
|
|
|
+ contributors (possibly including the lead) are generally supportive and
|
|
|
+ react with thumbs-up. If a proposal doesn't have these thumbs-up, the leads
|
|
|
+ together need to decide whether to move forward, and if so provide those
|
|
|
+ thumbs-up.
|
|
|
|
|
|
-- **GitHub pull requests** contain the proposals and related discussion.
|
|
|
- Resolved proposals will be committed with the associated decision. The pull
|
|
|
- request's description should link all related Discourse Forum topics and
|
|
|
- other references for easy browsing.
|
|
|
-- **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** may be used for early draft proposals. This facilitates
|
|
|
- collaborative editing and easy commenting about wording issues.
|
|
|
-- **Google 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.
|
|
|
+- If the leads choose to defer or reject the proposal, the reviewing lead
|
|
|
+ should explain why and close the PR.
|
|
|
|
|
|
-## Governance structure
|
|
|
+- Once the thumbs-up are present and the assigned lead finishes code review,
|
|
|
+ the lead should [approve](/docs/project/code_review.md#approving-the-change)
|
|
|
+ the PR. Any outstanding high-level concerns should be handled with blocking
|
|
|
+ issues.
|
|
|
|
|
|
-### Review managers
|
|
|
+- Optionally, the assigned lead can file a blocking issue for a one week final
|
|
|
+ comment period when they approve. This is rarely needed, and only when it is
|
|
|
+ both useful and important for the proposal to give extra time for community
|
|
|
+ comments.
|
|
|
|
|
|
-Review managers exist to help ensure proposals are reviewed in a timely fashion,
|
|
|
-regardless of whether it came from a long-time contributor or someone new to the
|
|
|
-community. They are expected to set aside personal opinions when ensuring a
|
|
|
-proposal is correctly reviewed, including abstaining from managing their own
|
|
|
-proposals. Proposal authors can always contact review managers if they're not
|
|
|
-sure what to do with a proposal.
|
|
|
+- The leads are responsible for resolving any blocking issues for a proposal
|
|
|
+ PR, including the one week comment period where resolving it indicates
|
|
|
+ comments arrived which require the proposal to undergo further review.
|
|
|
|
|
|
-The number of review managers isn't tightly restricted. Community members may
|
|
|
-volunteer their assistance as a way of contributing to Carbon, although the Core
|
|
|
-team will still review participation.
|
|
|
+- The proposal PR can be merged once the assigned lead approves, all blocking
|
|
|
+ issues have been decided, and any related decisions are incorporated.
|
|
|
|
|
|
-Our current review managers are:
|
|
|
+### Proposal roles
|
|
|
|
|
|
-- [jonmeow](https://github.com/jonmeow)
|
|
|
-- [mmdriley](https://github.com/mmdriley)
|
|
|
-- [sidney13](https://github.com/sidney13)
|
|
|
+It is also useful to see what the process looks like for different roles within
|
|
|
+the community. These perspectives are also the most critical to keep simple and
|
|
|
+easily understood.
|
|
|
|
|
|
-### Core team
|
|
|
+#### Proposal authors
|
|
|
|
|
|
-The core team is responsible for [setting Carbon's roadmap](roadmap_process.md)
|
|
|
-and managing evolution. This team should broadly understand both the users of
|
|
|
-Carbon and the project itself in order to factor different needs, concerns, and
|
|
|
-pressures into a
|
|
|
-[consensus decision-making process](consensus_decision_making.md).
|
|
|
+For proposal authors, this should feel like a code review, with some broken out
|
|
|
+issues for longer discussion:
|
|
|
|
|
|
-The team is expected to remain relatively small for efficiency, although members
|
|
|
-may be added when necessary to expand representation.
|
|
|
+- Create a proposal document and draft PR following
|
|
|
+ [the template](/proposals/template.md).
|
|
|
|
|
|
-Our current core team members are:
|
|
|
+ - [new_proposal.py](/proposals/scripts/new_proposal.py) helps create
|
|
|
+ templated PRs.
|
|
|
|
|
|
-- [austern](https://github.com/austern)
|
|
|
-- [chandlerc](https://github.com/chandlerc)
|
|
|
-- [geoffromer](https://github.com/geoffromer)
|
|
|
-- [gribozavr](https://github.com/gribozavr)
|
|
|
-- [josh11b](https://github.com/josh11b)
|
|
|
-- [noncombatant](https://github.com/noncombatant)
|
|
|
-- [tituswinters](https://github.com/tituswinters)
|
|
|
-- [zygoloid](https://github.com/zygoloid)
|
|
|
+ - If you have open questions, filing [blocking issues](#blocking-issues)
|
|
|
+ while preparing the PR can help resolve them quickly.
|
|
|
|
|
|
-**TODO**: We want this team to eventually include non-Googlers for a broader set
|
|
|
-of perspectives.
|
|
|
+- When ready, click on
|
|
|
+ ["Ready for review"](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/changing-the-stage-of-a-pull-request#marking-a-pull-request-as-ready-for-review)
|
|
|
+ in GitHub.
|
|
|
|
|
|
-#### Subteams
|
|
|
+ - This will result in the PR being assigned to an individual for review.
|
|
|
|
|
|
-As Carbon grows, the core team may decide to form subteams that provide
|
|
|
-leadership for specific areas. These subteams are expected to largely organize
|
|
|
-in a similar fashion to the core team, with a more narrow focus and scope. The
|
|
|
-escalation path for subteams goes first to the core team and then to the
|
|
|
-arbiters.
|
|
|
+ - This will also send the proposal as a broad RFC to the community.
|
|
|
|
|
|
-### Arbiters
|
|
|
+- Address comments where you can and they make sense.
|
|
|
|
|
|
-There may be issues where the core team cannot reach consensus even after
|
|
|
-careful discussion. In some cases, this simply means that the status quo must
|
|
|
-hold until a more compelling case for change has been made. However, to avoid
|
|
|
-important issues being unable to progress, any member of the community may
|
|
|
-request that an issue which failed to gain consensus be considered by the
|
|
|
-arbiters.
|
|
|
+- If you don't see an obvious way to address comments, that's OK.
|
|
|
|
|
|
-When acting as arbiters, the arbiters are only empowered to select between
|
|
|
-different options among which none achieved consensus, including maintaining
|
|
|
-status quo. All options must first be deliberated by the core team.
|
|
|
+ - It's great to engage a bit with the commenter to clarify their comment
|
|
|
+ or why you don't see an obvious way to address it, just like you would
|
|
|
+ [in code review](/docs/project/code_review.md#responding-to-review-comments).
|
|
|
|
|
|
-It is even more important that arbiters set aside any personal perspectives to
|
|
|
-the extent possible and make decisions in the interest of the project. They
|
|
|
-should typically bias towards maintaining the status quo and letting the
|
|
|
-proposal come back with more information rather than overriding it. It is
|
|
|
-expected to be relatively rare that the arbiters need to take on this role.
|
|
|
+ - If the commenter feels this is important, they can move it to a blocking
|
|
|
+ issue for a longer discussion and resolution from the leads.
|
|
|
|
|
|
-Arbiters may make a decision when at least two agree. If no two can agree, then
|
|
|
-the decision returns to the core team. For example, if an arbiter is
|
|
|
-unavailable, there may be a tie.
|
|
|
+ - You don't need to try to resolve everything yourself.
|
|
|
|
|
|
-There should always be three arbiters.
|
|
|
+- Incorporate any changes needed based on the resolution of blocking issues.
|
|
|
+ Once the leads have provided a resolution, it's important to make progress
|
|
|
+ with that direction.
|
|
|
|
|
|
-Our current arbiters are:
|
|
|
+- When you both have
|
|
|
+ [approval](/docs/project/code_review.md#approving-the-change) from the
|
|
|
+ assigned lead and the last blocking issue is addressed, merge!
|
|
|
|
|
|
-- [chandlerc](https://github.com/chandlerc)
|
|
|
-- [tituswinters](https://github.com/tituswinters)
|
|
|
-- [zygoloid](https://github.com/zygoloid)
|
|
|
+ - If you end up making significant changes when incorporating resolved
|
|
|
+ issues after the approval from the assigned lead, circle back for a
|
|
|
+ fresh approval before merging, just like you would with code review.
|
|
|
|
|
|
-### Painter
|
|
|
+#### Community
|
|
|
|
|
|
-Whenever possible, we want Carbon to make syntax and other decisions based on
|
|
|
-understanding its users, data, and the underlying goals of the language.
|
|
|
-However, there will be times when those don't provide a clear cut rationale for
|
|
|
-any particular decision -- all of the options are fine/good and someone simply
|
|
|
-needs to choose which color to paint the bikeshed. The goal of the painter role
|
|
|
-is to have a simple way to quickly decide these points.
|
|
|
+- We use the
|
|
|
+ [Proposals dashboard](https://github.com/carbon-language/carbon-lang/projects/1)
|
|
|
+ to track proposals that are in RFC.
|
|
|
|
|
|
-Any team may defer a decision to the painter if there is a consensus that it is
|
|
|
-merely a bikeshed in need of paint. The team may also open an issue to revisit
|
|
|
-the color with data and/or user studies of some kind. This allows progress to be
|
|
|
-unblocked while also ensuring we return to issues later and attempt to find more
|
|
|
-definite rationale.
|
|
|
+ - Anyone that is interested can participate once a proposal is ready for
|
|
|
+ review and in RFC.
|
|
|
|
|
|
-The painter is a single person in order to keep decisions around taste or
|
|
|
-aesthetics reasonably consistent.
|
|
|
+ - It's OK to only comment when particularly interested in a proposal, or
|
|
|
+ when asked by one of the leads to help ensure thorough review. Not
|
|
|
+ everyone needs to participate heavily in every RFC.
|
|
|
|
|
|
-The current painter is:
|
|
|
+ - PRs that are in "draft" status in GitHub are considered
|
|
|
+ works-in-progress. Check with the author before spending time reviewing
|
|
|
+ these, and generally avoid distracting the author with comments unless
|
|
|
+ they ask for them. The proposal may be actively undergoing edits.
|
|
|
|
|
|
-- [chandlerc](https://github.com/chandlerc)
|
|
|
+- Read the proposal and leave comments to try to help make the proposal an
|
|
|
+ improvement for Carbon.
|
|
|
|
|
|
-### Adding and removing governance members
|
|
|
+ - Note that progress and improvement are more important than perfection
|
|
|
+ here!
|
|
|
|
|
|
-Any member of Carbon governance may step down or be replaced when they are no
|
|
|
-longer able to contribute effectively. The core team can nominate and decide on
|
|
|
-adding, removing, or replacing members using the usual evolution processes.
|
|
|
+- Try to make comments on proposals
|
|
|
+ [constructive](/docs/project/code_review.md#writing-review-comments).
|
|
|
+ Suggest how the proposal could be better if at all possible.
|
|
|
|
|
|
-## Evolution process
|
|
|
+- If there is an open question or a critical blocking issue that needs to get
|
|
|
+ resolved, move it to its own issue that the PR depends on, and focus the
|
|
|
+ discussion there.
|
|
|
|
|
|
-### When to follow the evolution process
|
|
|
+ - The issue should focus on surfacing the important aspects of the
|
|
|
+ tradeoff represented by the issue or open question, not on advocacy.
|
|
|
|
|
|
-Any substantive change to Carbon -- whether the language, project,
|
|
|
-infrastructure, or otherwise -- should follow the evolution process. The meaning
|
|
|
-of "substantive" is subjective, but will generally include:
|
|
|
+#### Active contributors
|
|
|
|
|
|
-- Any semantic or syntactic language change that isn't fixing a bug.
|
|
|
-- Major changes to project infrastructure, including additions and removals.
|
|
|
-- Changes to the process itself.
|
|
|
-- Rolling back a finalized decision, even if never executed.
|
|
|
+Everyone actively contributing to the evolution of Carbon should try to
|
|
|
+regularly:
|
|
|
|
|
|
-Changes which generally will not require this process are:
|
|
|
+- Give a thumbs-up or other reaction on any interesting PRs out for RFC to
|
|
|
+ help surface general enthusiasm for the high level idea or direction. Don't
|
|
|
+ worry about "approving" or the details here.
|
|
|
|
|
|
-- Fixing typos or bugs that don't change the meaning and/or intent.
|
|
|
-- Rephrasing or refactoring documentation for easier reading.
|
|
|
-- Minor infrastructure updates, improvements, setting changes, tweaks.
|
|
|
+- If interested and time permitting, dive into some RFCs and provide
|
|
|
+ [community feedback](#community).
|
|
|
|
|
|
-If you're not sure whether to follow the process, please err on the side of
|
|
|
-following it. A team can always ask for a change to be made directly if they
|
|
|
-believe it doesn't need review. Conversely, a reviewer might also ask that a
|
|
|
-pull request instead go through the full evolution process.
|
|
|
+#### Carbon leads
|
|
|
|
|
|
-### Draft the proposal
|
|
|
+[Carbon leads](#carbon-leads-1) are responsible for making decisions rapidly and
|
|
|
+ensuring proposal PRs land:
|
|
|
|
|
|
-#### (optional) Discuss the idea early
|
|
|
+- Rapidly resolve all blocking issues raised across any proposals.
|
|
|
|
|
|
-We encourage proposal authors to discuss problems they're trying to solve and
|
|
|
-their ideas for addressing it with the community early using any of our
|
|
|
-coordination tools. The goal should be to get a feel for any prior work, as well
|
|
|
-as other ideas or perspectives on both the problem and ways of approaching it.
|
|
|
+- When assigned a specific proposal PR:
|
|
|
|
|
|
-These discussions can also help socialize both the problem and ideas with the
|
|
|
-community, making subsequent discussions around a concrete proposal more
|
|
|
-efficient.
|
|
|
+ - Make sure it gets both constructive general comments and good code
|
|
|
+ review.
|
|
|
|
|
|
-##### Actions
|
|
|
+ - Ideally, you should directly participate in the code review, but it's
|
|
|
+ fine to ask others to help. However, ultimately you have to review and
|
|
|
+ approve the PR.
|
|
|
|
|
|
-- **Author**: Create an `Evolution > Ideas` topic to discuss the issue before
|
|
|
- writing the proposal.
|
|
|
-- **Community**: Provide [constructive commentary](commenting_guidelines.md)
|
|
|
- for ideas when feedback is solicited.
|
|
|
+ - Escalate any blocking issues without a resolution that are slowing down
|
|
|
+ the proposal to the other leads.
|
|
|
|
|
|
-#### Make a proposal
|
|
|
+ - Evaluate whether an extended final comment period is important for the
|
|
|
+ community given the nature of the proposal.
|
|
|
|
|
|
-We use a [template for proposals](/proposals/template.md) to make it easier for
|
|
|
-readers to recognize the style and structure. Follow the instructions under
|
|
|
-"TODO: Initial proposal setup".
|
|
|
+### When to write a proposal
|
|
|
|
|
|
-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.
|
|
|
+Any substantive change to Carbon -- whether the language, project,
|
|
|
+infrastructure, or otherwise -- should be done through an evolution proposal.
|
|
|
+The meaning of "substantive" is subjective, but will generally include:
|
|
|
+
|
|
|
+- Any semantic or syntactic language change that isn't fixing a bug.
|
|
|
+- Major changes to project infrastructure, including additions and removals.
|
|
|
+- Rolling back an accepted proposal, even if never executed.
|
|
|
|
|
|
-The proposal's pull request may include changes in the same repository. 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.
|
|
|
+Changes which generally will not require a proposal are:
|
|
|
|
|
|
-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
|
|
|
-options, compare their advantages, disadvantages, and non-trivial consequences.
|
|
|
-These may be resolved during discussion, or be left for decision by the
|
|
|
-reviewing team.
|
|
|
+- Fixing typos or bugs that don't change the meaning or intent.
|
|
|
+- Rephrasing or refactoring documentation for easier reading.
|
|
|
+- Minor infrastructure updates, improvements, setting changes, tweaks.
|
|
|
|
|
|
-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.
|
|
|
+If you're not sure whether to write a proposal, please err on the side of
|
|
|
+writing a proposal. A team can always ask for a change to be made directly if
|
|
|
+they believe it doesn't need review. Conversely, a reviewer might also ask that
|
|
|
+a pull request instead go through the full evolution process.
|
|
|
|
|
|
-##### Drafting using Google Docs
|
|
|
+### Proposal PRs
|
|
|
|
|
|
-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 proposal with multiple authors.
|
|
|
+A proposal PR should use the `proposal` label, have a descriptive title, and
|
|
|
+easily understood initial summary comment. Authors and leads are encouraged to
|
|
|
+edit both as necessary to ensure they give the best high-level understanding of
|
|
|
+the proposal possible. The proposals should then use the
|
|
|
+[template file](/proposals/template.md) to describe itself fully.
|
|
|
|
|
|
-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.
|
|
|
+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.
|
|
|
|
|
|
-If you use Google Docs for drafting, be sure to still use a Markdown pull
|
|
|
-request for the RFC.
|
|
|
+Proposal PRs will often lead to related changes to the rest of the Carbon
|
|
|
+project. These changes may be added to the proposal PR itself, they may be done
|
|
|
+in other PRs that are referenced for context, or they may be stand-alone changes
|
|
|
+that are implemented through a series of future PRs to the rest of the project.
|
|
|
+All of these options are fine.
|
|
|
+
|
|
|
+#### Open questions
|
|
|
+
|
|
|
+Feel free to factor out open questions in a proposal to issues that you assign
|
|
|
+to the leads to resolve. You can even do this before sending the proposal for
|
|
|
+review. Even after it's resolved, an open question issue can be reopened if new
|
|
|
+information comes up during the RFC.
|
|
|
+
|
|
|
+When opening issues, add them to the
|
|
|
+["Issues for leads" project](https://github.com/carbon-language/carbon-lang/projects/2)
|
|
|
+under "Questions". Carbon leads use this to locate and prioritize the issue for
|
|
|
+resolution.
|
|
|
+
|
|
|
+### Review and RFC on proposal PRs
|
|
|
+
|
|
|
+When a proposal PR is assigned to the
|
|
|
+[carbon-leads GitHub group](https://github.com/orgs/carbon-language/teams/carbon-leads),
|
|
|
+one of them will be assigned the PR. They are responsible for helping land that
|
|
|
+proposal, or explaining why the project won't move forward in that direction.
|
|
|
+The assigned lead is also ultimately responsible for the code review on the PR.
|
|
|
+Proposals sent for review are also sent as an RFC to the entire community.
|
|
|
+
|
|
|
+All active Carbon contributors are strongly encouraged to regularly skim the
|
|
|
+title and summary comment of proposals under RFC that are interesting to them.
|
|
|
+They should use GitHub reactions, including at least a thumbs-up, to show their
|
|
|
+interest and enthusiasm about the proposal, and help encourage the author.
|
|
|
+Writing proposals is _extremely hard work_, and we need to clearly show both
|
|
|
+interest in the proposed direction of Carbon and appreciation for the work put
|
|
|
+into the proposal. This is not about _approving_ the proposal, or any of its
|
|
|
+details. It is completely fine and coherent to both give a thumbs-up to a
|
|
|
+proposal _and_ provide a serious, blocking issue that needs to be resolved.
|
|
|
+
|
|
|
+_Anyone_ in the community is welcome to participate in the RFC in detail if
|
|
|
+interested. However, not everyone needs to participate in every RFC. If a
|
|
|
+proposal is already getting actively and thoroughly reviewed, feel free to focus
|
|
|
+your time on other proposals with fewer commenters. Even if there are issues or
|
|
|
+problems discovered later, we can always fix them with follow-up proposals.
|
|
|
+
|
|
|
+Both code review and high-level design comments are welcome. If an open question
|
|
|
+comes up or a high-level blocking issue is uncovered, feel free to move it to
|
|
|
+its own GitHub issue and assign it to the leads to resolve. That issue is also a
|
|
|
+good place to focus discussion on that specific topic rather than the main PR.
|
|
|
+
|
|
|
+The assigned lead should approve proposals once the following criteria are met:
|
|
|
+
|
|
|
+- It looks good from a code review perspective.
|
|
|
+
|
|
|
+- At least three thumbs-up reactions showing general community interest.
|
|
|
+
|
|
|
+- The community has had a sufficient opportunity to review the proposed
|
|
|
+ change, given its scope and complexity.
|
|
|
+
|
|
|
+- Any remaining blocking issues are reasonably likely to resolve in a way that
|
|
|
+ allows the proposal to move forward. It is fine if some are not fully
|
|
|
+ decided, but a lead shouldn't approve a proposal that's unlikely to move
|
|
|
+ forward.
|
|
|
+
|
|
|
+The last two criteria are fundamentally judgement calls for the lead to make,
|
|
|
+and we don't try to formulate a rigid or fixed bar for them. If resolving the
|
|
|
+blocking issues requires significant changes, the author should also get a fresh
|
|
|
+approval from the assigned lead after those changes, just like they would with
|
|
|
+code review.
|
|
|
+
|
|
|
+The assigned lead may also request a final comment period for the community when
|
|
|
+approving. This signals to the community that the proposal is likely to be
|
|
|
+merged once the blocking issues are resolved, and any remaining concerns need to
|
|
|
+be surfaced. The goal is to help uncover concerns that were hidden until it was
|
|
|
+clear that the proposal is likely to move forward. However, requesting a final
|
|
|
+comment period is not the default; the assigned lead should only do this when
|
|
|
+there is some reason to expect further community comment is especially important
|
|
|
+to solicit. Common cases to consider are contentious, complex, or dramatic
|
|
|
+changes to the language or project. Ultimately, whether this is important is a
|
|
|
+judgement call for the lead. This will be modeled by filing a blocking issue
|
|
|
+that resolves in one week when approving. This issue will also explain the
|
|
|
+motivation for requesting a final comment period.
|
|
|
+
|
|
|
+### Blocking issues
|
|
|
+
|
|
|
+We use blocking GitHub issues to track open questions or other discussions that
|
|
|
+the leads are asked to resolve. Any time a blocking issue is filed, that issue
|
|
|
+forms both the primary discussion thread and where the leads signal how it is
|
|
|
+resolved. We use issues both to track that there is a specific resolution
|
|
|
+expected and that there may be dependencies.
|
|
|
+
|
|
|
+We add blocking issues to the
|
|
|
+["Issues for leads" project](https://github.com/carbon-language/carbon-lang/projects/2)
|
|
|
+under "Blocking issues". Carbon leads use this to locate and prioritize the
|
|
|
+issue for resolution.
|
|
|
+
|
|
|
+These issues can be created at any time and by any one. Issues can be created
|
|
|
+while the proposal is being drafted in order to help inform specific content
|
|
|
+that should go into the proposal. It is even fine to create an issue first, even
|
|
|
+before a proposal exists, as an open question about whether to produce a
|
|
|
+particular proposal, or what a proposal that is being planned should say. For
|
|
|
+issues which don't (yet) have a specific proposal PR associated with them, at
|
|
|
+some point the leads may ask that a proposal be created to help collect in a
|
|
|
+more cohesive place a written overview of the issue and related information, but
|
|
|
+this process need not be strictly or rigidly bound to having proposal text.
|
|
|
+
|
|
|
+Avoid using issues for things that are just requests or suggestions on a
|
|
|
+proposal PR. If in doubt, start off with a simple comment on the PR and see if
|
|
|
+there is any disagreement -- everyone may already be aligned and agree. When a
|
|
|
+comment does seem worth turning into an issue, don't worry about that as the
|
|
|
+author or the commenter. Getting the leads to resolve disagreement isn't a bad
|
|
|
+thing for anyone involved. This should be seen as a friendly way to move the
|
|
|
+discussion out to its own forum where it'll get resolved, and focus the PR on
|
|
|
+improving the proposal and getting it ready to merge.
|
|
|
+
|
|
|
+When an issue is created from a discussion on a PR, and after the discussion on
|
|
|
+the _issue_ all the original parties come to a happy agreement, it's totally OK
|
|
|
+to close the issue and move back to the code review in the PR. Anyone who would
|
|
|
+prefer the leads to still chime in can re-open the issue and the leads will
|
|
|
+follow up, even if it's only to get confirmation that everyone _did_ end up
|
|
|
+happy with the resolution. At the end of the day, while it's fine to resolve an
|
|
|
+issue that _everyone_ actually ended up agreeing about (maybe once some
|
|
|
+confusion is addressed), ultimately the leads are responsible for resolving
|
|
|
+these issues and there is no pressure on anyone else to do so.
|
|
|
+
|
|
|
+#### Discussion on blocking issues
|
|
|
+
|
|
|
+Discussion on these issues, especially contentious ones, should endeavor to
|
|
|
+focus on surfacing information and highlighting the nature of the tradeoff
|
|
|
+implied by the decisions available. This is in contrast to focusing on advocacy
|
|
|
+or persuasion. The goal of the issues shouldn't be to persuade or convince the
|
|
|
+leads to make a specific decision, but to give the leads the information they
|
|
|
+need to make the best decision for Carbon.
|
|
|
+
|
|
|
+It's fine that some people have a specific belief of which decision would be
|
|
|
+best; however, framing their contributions to the discussion as surfacing the
|
|
|
+information that underpins that belief will make the discussion more
|
|
|
+constructive, welcoming, and effective. Overall, everyone should strive to
|
|
|
+minimize their use of [rhetoric](https://en.wikipedia.org/wiki/Rhetoric) or
|
|
|
+other
|
|
|
+[persuasive methods](https://en.wikipedia.org/wiki/Persuasion#List_of_methods)
|
|
|
+to the extent they can.
|
|
|
+
|
|
|
+None of this should preclude gathering information like polls of opinion among
|
|
|
+groups, or signaling agreement. Where community members stand and how many agree
|
|
|
+with that stance on any issue _is_ information, and useful to surface.
|
|
|
|
|
|
-##### Actions
|
|
|
+## Governance structure
|
|
|
|
|
|
-- **Author**:
|
|
|
- - Write the proposal using [the template](/proposals/template.md).
|
|
|
- - The template has additional actions under "TODO: Initial proposal
|
|
|
- setup".
|
|
|
+### Carbon leads
|
|
|
|
|
|
-#### (optional) Elicit early, high-level feedback on the proposal
|
|
|
+Carbon leads are responsible for reviewing proposals and
|
|
|
+[setting Carbon's roadmap](roadmap_process.md) and managing evolution. This team
|
|
|
+should broadly understand both the users of Carbon and the project itself in
|
|
|
+order to factor different needs, concerns, and pressures into a
|
|
|
+[consensus decision-making process](https://en.wikipedia.org/wiki/Consensus_decision-making).
|
|
|
|
|
|
-Authors may continue to use the `Evolution > Ideas` topic to advertise the
|
|
|
-proposal and elicit early, high-level feedback. Community commenters should
|
|
|
-favor GitHub comments over forum topic replies.
|
|
|
+While leads may approve proposals individually, they should decide on issues
|
|
|
+raised to them using
|
|
|
+[blocking consensus](https://en.wikipedia.org/wiki/Consensus_decision-making#Blocking)
|
|
|
+with a quorum of two.
|
|
|
|
|
|
-##### Actions
|
|
|
+Carbon's current leads are:
|
|
|
|
|
|
-- **Author**: Update, or create if needed, the `Evolution > Ideas` topic to
|
|
|
- advertise the proposal and elicit early, high-level feedback.
|
|
|
- - Add the topic's link to the GitHub pull request.
|
|
|
-- **Community**: Provide [constructive commentary](commenting_guidelines.md)
|
|
|
- for ideas when feedback is solicited.
|
|
|
+- [chandlerc](https://github.com/chandlerc)
|
|
|
+- [KateGregory](https://github.com/KateGregory)
|
|
|
+- [zygoloid](https://github.com/zygoloid)
|
|
|
|
|
|
-### Solicit and address proposal feedback
|
|
|
+#### Subteams
|
|
|
|
|
|
-#### Request comments
|
|
|
+As Carbon grows, the leads may decide to form subteams that provide leadership
|
|
|
+for specific areas. These subteams are expected to largely organize in a similar
|
|
|
+fashion to the Carbon leads, with a more narrow focus and scope. Subteam
|
|
|
+decisions may be escalated to the Carbon leads.
|
|
|
|
|
|
-Once authors feel the proposal is in good shape for wider evaluation from the
|
|
|
-reviewing team, they begin the more formal process of evaluation by creating an
|
|
|
-`Evolution > RFCs` topic for technical review of the proposal.
|
|
|
+### Painter
|
|
|
|
|
|
-The topic should start off with a brief summary of the proposal and any prior
|
|
|
-discussion, as well as links to prior discussion topics.
|
|
|
+Whenever possible, we want Carbon to make syntax and other decisions based on
|
|
|
+understanding its users, data, and the underlying goals of the language.
|
|
|
+However, there will be times when those don't provide a clear cut rationale for
|
|
|
+any particular decision -- all of the options are fine/good and someone simply
|
|
|
+needs to choose which color to paint the bikeshed. The goal of the painter role
|
|
|
+is to have a simple way to quickly decide these points.
|
|
|
|
|
|
-##### Actions
|
|
|
+Leads and teams may defer a decision to the painter if there is a consensus that
|
|
|
+it is merely a bikeshed in need of paint. They may also open an issue to revisit
|
|
|
+the color with data and/or user studies of some kind. This allows progress to be
|
|
|
+unblocked while also ensuring we return to issues later and attempt to find more
|
|
|
+definite rationale.
|
|
|
|
|
|
-- **Author**:
|
|
|
- - Replace the GitHub pull request's `WIP` label with `RFC`.
|
|
|
- - Create an `Evolution > RFCs` topic.
|
|
|
- - Summarize the discussion points, along with a link to the pull
|
|
|
- request.
|
|
|
- - Add the topic's link to the pull request's description.
|
|
|
+The painter is a single person in order to keep decisions around taste or
|
|
|
+aesthetics reasonably consistent.
|
|
|
|
|
|
-#### Community and reviewing team comments on proposal
|
|
|
+The current painter is:
|
|
|
|
|
|
-Anyone in the community is welcome to
|
|
|
-[comment on an RFC](commenting_guidelines.md). The reviewing team is _expected_
|
|
|
-to participate at least enough to provide any relevant feedback.
|
|
|
+- [chandlerc](https://github.com/chandlerc)
|
|
|
|
|
|
-Proposal authors should actively engage in the discussion and incorporate
|
|
|
-changes to reflect feedback. Work to improve the proposal through incorporating
|
|
|
-feedback. Authors should explicitly mention when they believe a comment has been
|
|
|
-addressed, and commenters should be clear and explicit about whether they
|
|
|
-believe more changes are needed.
|
|
|
+### Adding and removing governance members
|
|
|
|
|
|
-When significant alternatives are pointed out, include them in the proposal
|
|
|
-regardless of whether they're adopted. The "alternatives" section should be used
|
|
|
-to document rejected alternatives as well as the original approach when an
|
|
|
-alternative is adopted, with advantages and disadvantages either way. New "open
|
|
|
-questions" may also be added where the author isn't confident about the best
|
|
|
-approach.
|
|
|
-
|
|
|
-##### Actions
|
|
|
-
|
|
|
-- **Author**: Update the proposal and/or reply to comments to address
|
|
|
- feedback.
|
|
|
-- **Reviewing team and community**: Provide
|
|
|
- [constructive commentary](commenting_guidelines.md) for proposals.
|
|
|
-
|
|
|
-#### (optional) Pause for a major revision
|
|
|
-
|
|
|
-Significant changes to the proposal may become necessary as a result of the
|
|
|
-discussion. At that point, the authors should clearly state that they are
|
|
|
-planning a revision and the issue should be marked as `WIP` again. At this
|
|
|
-point, the community should prioritize giving the authors time and space to work
|
|
|
-on the revision rather than sending more feedback.
|
|
|
-
|
|
|
-The author should treat this as going back to the draft phase. When a new
|
|
|
-revision is ready, the authors start a new
|
|
|
-[request for comments](#request-comments) with an updated summary of the
|
|
|
-discussion points thus far. Links to prior topics should be included.
|
|
|
-
|
|
|
-##### Actions
|
|
|
-
|
|
|
-- **Author**:
|
|
|
- - Announce to the Discourse Forum topic that the proposal is undergoing
|
|
|
- major revision.
|
|
|
- - Replace the GitHub pull request's `RFC` label with `WIP`.
|
|
|
-- **Reviewing team and community**: Refrain from commenting until the author
|
|
|
- solicits feedback again.
|
|
|
-
|
|
|
-#### Request a review manager
|
|
|
-
|
|
|
-Once discussion settles down and all comments have been resolved, the author
|
|
|
-should ask for a review manager either on the RFC topic with `@review_managers`
|
|
|
-or on `#proposals` in Discord Chat. A review manager should respond within a day
|
|
|
-or two. This may not be needed if a review manager has already taken ownership.
|
|
|
-
|
|
|
-The review manager is responsible for validating that the proposal is ready for
|
|
|
-the reviewing team to make a decision. They will ensure that at least a couple
|
|
|
-members of the reviewing team have reviewed the document before it leaves RFC.
|
|
|
-
|
|
|
-The review manager will announce a planned end to the community comment period
|
|
|
-on the "Evolution > RFCs" topic. The message will specify the end date, which
|
|
|
-will be at least one week or four working days after the announcement, whichever
|
|
|
-is later. If nothing significant arises, the reviewing team will be asked to
|
|
|
-start making a decision as scheduled. Otherwise, the review manager may extend
|
|
|
-the comment period by posting another message to the "Evolution > RFCs" topic.
|
|
|
-
|
|
|
-##### Actions
|
|
|
-
|
|
|
-- **Author**:
|
|
|
- - Ensure all comments are resolved.
|
|
|
- - Ask for a review manager on either the RFC topic or `#proposals` in
|
|
|
- Discord chat.
|
|
|
-- **Review manager**:
|
|
|
- - Ask reviewing team members to review the proposal when needed.
|
|
|
- - Double-check for comment threads that the author may have missed before
|
|
|
- proceeding.
|
|
|
- - [Update](review_managers.md#comment-deadline) the `Evolution > RFCs`
|
|
|
- topic with a last call for comments.
|
|
|
- - Add the `comment deadline` label to the GitHub pull request.
|
|
|
-
|
|
|
-### 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 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**: Stop making changes to the proposal.
|
|
|
-
|
|
|
-#### Ask the reviewing team for a proposal decision
|
|
|
-
|
|
|
-The review manager should ask the reviewing team for a decision by creating an
|
|
|
-`Evolution > Proposal decisions` topic asking for consensus. The proposal should
|
|
|
-also be added as a topic to the team's meeting agenda one week or four working
|
|
|
-days in advance, whichever is longer. The agenda item gives a deadline for a
|
|
|
-decision if no consensus can be reached on the Discourse Forum, and can be
|
|
|
-removed if a decision is made before the meeting.
|
|
|
-
|
|
|
-Team members should familiarize themselves with the proposal and related
|
|
|
-discussion. Try to respond to the Discourse Forum topic promptly with:
|
|
|
-
|
|
|
-- A position, either affirming or objecting, is strongly preferred. Standing
|
|
|
- aside is allowed.
|
|
|
- - Rationales for positions should be based on discussion on the proposal's
|
|
|
- `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.
|
|
|
- - The reviewing team will participate in the proposal community comment
|
|
|
- period, so that substantive feedback can be incorporated by the author
|
|
|
- prior 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 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.
|
|
|
-If no decision can be reached before the meeting, the meeting will be used to
|
|
|
-make decisions.
|
|
|
-
|
|
|
-##### Actions
|
|
|
-
|
|
|
-- **Author**:
|
|
|
- - Respond to comments.
|
|
|
-- **Review manager:**
|
|
|
- - Double-check for comment threads that the author may have missed before
|
|
|
- proceeding.
|
|
|
- - Replace the GitHub pull request's `RFC` and `comment deadline` labels
|
|
|
- with `needs decision`.
|
|
|
- - [Create](review_managers.md#decision-request) 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
|
|
|
- consensus.
|
|
|
- - Monitor the topic for a consensus decision.
|
|
|
- - If a consensus is reached, ensure there's enough information to
|
|
|
- write a decision.
|
|
|
-- **Every reviewing team member:**
|
|
|
- - Review the proposal again and make comments if needed.
|
|
|
- - Participate in reaching a consensus, or explicitly stand aside.
|
|
|
- - Offer justifications towards a decision.
|
|
|
-
|
|
|
-#### (optional) Use the meeting to make a proposal decision
|
|
|
-
|
|
|
-If the reviewing team fails to reach consensus before the meeting, the
|
|
|
-[weekly meeting](consensus_decision_making.md#meetings) should be used to reach
|
|
|
-consensus. The review manager is encouraged to volunteer as the note taker for
|
|
|
-the meeting, and should help ensure there's a moderator. The author and other
|
|
|
-community members may attend, but should behave as observers unless explicitly
|
|
|
-called on to answer a question by the core team.
|
|
|
-
|
|
|
-The reviewing team is responsible for producing a decision at the end of the
|
|
|
-meeting, even if it is to defer the proposal. The review manager should verify
|
|
|
-they understand the decision, because they will be responsible for publishing
|
|
|
-it.
|
|
|
-
|
|
|
-- **Author**: (optional) Consider attending the meeting to better understand
|
|
|
- the proposal decision.
|
|
|
-- **Review manager**:
|
|
|
- - Help identify a
|
|
|
- [moderator and note taker](consensus_decision_making.md#roles) for the
|
|
|
- meeting, possibly volunteering as note taker.
|
|
|
- - Ensure the meeting provides enough information to write a decision.
|
|
|
-- **Reviewing team**:
|
|
|
- - Participate in reaching a consensus, or explicitly stand aside.
|
|
|
- - Offer justifications towards a decision.
|
|
|
-
|
|
|
-### Finalize the proposal decision
|
|
|
-
|
|
|
-#### Publish the proposal decision
|
|
|
-
|
|
|
-Once a decision has been reached, the review manager will draft a
|
|
|
-[formal decision](consensus_decision_making.md#formal-decision-content) based on
|
|
|
-Discourse Forums discussion and, if provided, the meeting notes. They will post
|
|
|
-the draft decision to the `Evolution > Announcements` forum within two working
|
|
|
-days. The post will start the proposal decision comment period.
|
|
|
-
|
|
|
-If the proposal is accepted, the author may now commit it. If it is deferred or
|
|
|
-declined, the author may decide how to proceed based on whether they'd like to
|
|
|
-continue working on it.
|
|
|
-
|
|
|
-##### Actions
|
|
|
-
|
|
|
-- **Review manager**:
|
|
|
- - Write the
|
|
|
- [formal decision](consensus_decision_making.md#formal-decision-content),
|
|
|
- possibly with help from the reviewing team.
|
|
|
- - (optional): Create a GitHub issue for issues that should be
|
|
|
- revisited in the future. Link to these from the GitHub pull request.
|
|
|
- - If the proposal was accepted:
|
|
|
- - Prepare a GitHub pull request with the decision.
|
|
|
- - [Create](review_managers.md#decision-announcement) an
|
|
|
- `Evolution > Announcements` topic and link to the proposal and
|
|
|
- decision pull requests.
|
|
|
- - Add the topic's link to the proposal's pull request.
|
|
|
- - Approve the proposal's pull request for commit.
|
|
|
- - If the proposal was deferred or declined:
|
|
|
- - Comment on the proposal's pull request with the decision.
|
|
|
- - Create an `Evolution > Announcements` topic and link to the proposal
|
|
|
- and decision comment.
|
|
|
-- **Author**:
|
|
|
- - If the proposal is accepted:
|
|
|
- - Replace the GitHub pull request's `needs decision` label with
|
|
|
- `accepted`.
|
|
|
- - Commit the approved pull request.
|
|
|
- - If the proposal was deferred or declined, decide how best to proceed:
|
|
|
- - If iterating on the proposal, replace the GitHub pull request's
|
|
|
- `needs decision` label with `WIP`.
|
|
|
- - If retracting the proposal, close the pull request.
|
|
|
-- **Reviewing team**: Help draft any rationale needed by the review manager
|
|
|
- for the decision.
|
|
|
-
|
|
|
-#### Community comments on proposal decision
|
|
|
-
|
|
|
-When the proposal decision is published, it enters a comment period. The comment
|
|
|
-period lasts two weeks, ensuring at least five working days. During this period,
|
|
|
-the decision is in effect, although dependent changes should be made only if
|
|
|
-they are easy to roll back.
|
|
|
-
|
|
|
-When commenting on the decision, the community should keep in mind that the goal
|
|
|
-of the decision is to continue to evolve Carbon in a positive direction.
|
|
|
-Constructive criticism can improve the framing of the decision. The comment
|
|
|
-period should not be used to continue to debate decisions unless raising
|
|
|
-specific new information. When commenting, some questions you might want to
|
|
|
-address are:
|
|
|
-
|
|
|
-- Is the decision clear in its conclusion?
|
|
|
-- Does the decision explain its rationale well?
|
|
|
-- Have concerns or alternatives been effectively understood, acknowledged, and
|
|
|
- addressed to the extent possible?
|
|
|
-
|
|
|
-If the decision is to accept the proposal, the author may start making changes
|
|
|
-described in the proposal which are easy to roll back before the decision review
|
|
|
-ends. If the author starts making changes, they must agree to help roll back
|
|
|
-changes if the decision is rolled back. This does not mean that the decision is
|
|
|
-final; however, we prefer to maintain velocity and roll back when needed. The
|
|
|
-reviewing team may additionally decide that some changes _must_ wait until the
|
|
|
-decision review is complete; for example, if members are concerned that rollback
|
|
|
-costs are non-obvious.
|
|
|
-
|
|
|
-##### Actions
|
|
|
-
|
|
|
-- **Author:** (optional) Start making dependent changes which are easy to roll
|
|
|
- back, and be prepared to roll back if needed.
|
|
|
-- **Review manager:** Respond to comments and bring any significant issues to
|
|
|
- the reviewing team's attention.
|
|
|
-- **Community and reviewing team**: Provide
|
|
|
- [constructive commentary](commenting_guidelines.md) for the proposal
|
|
|
- decision.
|
|
|
-
|
|
|
-#### (optional) Rollback the decision
|
|
|
-
|
|
|
-If important new information is provided, the reviewing team will engage and, if
|
|
|
-necessary, rollback their decision. Any reviewing team member may start this by
|
|
|
-stating their new position on the reviewing team's decision topic, although this
|
|
|
-should be exceptional.
|
|
|
-
|
|
|
-##### Actions
|
|
|
-
|
|
|
-- **Author**: Roll back the committed proposal and any dependent changes.
|
|
|
-- **Reviewing team member**: State new, non-consensus position on
|
|
|
- `Evolution > Decisions` topic.
|
|
|
-- **Review manager**:
|
|
|
- - Update the `Evolution > Announcements` topic to reflect the rollback.
|
|
|
- - Return to
|
|
|
- [asking the reviewing team for a proposal decision](#ask-the-reviewing-team-for-a-proposal-decision).
|
|
|
-
|
|
|
-#### Execute on proposal decision
|
|
|
-
|
|
|
-When the comment period ends without objections from the reviewing team, the
|
|
|
-review manager should finalize the decision: accepted, deferred, declined, etc.
|
|
|
-
|
|
|
-If the decision is to accept the proposal, the author may make the changes
|
|
|
-described in the proposal. There may still be review comments, but those should
|
|
|
-focus on the **document**: formatting, structure, links, etc. The proposal
|
|
|
-should **not** be re-argued on the decision review.
|
|
|
-
|
|
|
-That does not mean that all decisions are final! Everyone involved in a decision
|
|
|
-is human and we all make mistakes. However, once there is a clear decision,
|
|
|
-reversing or reconsidering it should take the form of a new proposal and follow
|
|
|
-the process of a new proposal. It may be substantially shorter to write up, but
|
|
|
-often it will be important to clearly and carefully explain the reason to
|
|
|
-revisit the decision.
|
|
|
-
|
|
|
-##### Actions
|
|
|
-
|
|
|
-- **Review manager**:
|
|
|
- - Update the `Evolution > Announcements` topic with the final decision.
|
|
|
- - If the proposal was accepted, commit the proposal decision.
|
|
|
-- **Author**: Start making dependent changes to apply the proposal.
|
|
|
+Any member of Carbon governance may step down or be replaced when they are no
|
|
|
+longer able to contribute effectively. The Carbon leads can nominate and decide
|
|
|
+on adding, removing, or replacing members using the usual evolution processes.
|
|
|
|
|
|
## Acknowledgements
|
|
|
|
Jon Meow