carbon-language/carbon-lang
1
0
Fork 0
mirror of https://github.com/carbon-language/carbon-lang.git synced 2026-10-05 22:02:55 +01:00
Code Issues Packages Projects Releases 10 Wiki Activity

Set up Prettier for formatting, and run files through it. (#7)

Browse Source 
CONTRIBUTING.md replaces the mention of Google style guide (which isn't automated) with Prettier (which should do most of the hauling). The rest is the formatter.
This commit is contained in:
Jon Meow
2020-05-07 09:29:23 -07:00
committed by GitHub
parent 94c6bc9a3f
commit f1a67a89b6
7 changed files with 431 additions and 442 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/project/evolution.md
+182 -188
View File
@@ -18,15 +18,14 @@ bounded timeframe.
Our governance structure supports
[consensus decision-making](consensus_decision_making.md):
* 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.
- 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.
## Evolution process
@@ -68,22 +67,21 @@ The process is:
We use several tools to coordinate changes to Carbon:
* **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.
- **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.
## Governance structure
@@ -102,8 +100,8 @@ team will still review participation.
Our current review managers are:
* [jperkins@google.com](mailto:jperkins@google.com)
* [shummert@google.com](mailto:shummert@google.com)
- [jperkins@google.com](mailto:jperkins@google.com)
- [shummert@google.com](mailto:shummert@google.com)
### Core team
@@ -118,14 +116,14 @@ may be added when necessary to expand representation.
Our current core team members are:
* austern@google.com
* chandlerc@google.com
* dmitrig@google.com
* gromer@google.com
* joshl@google.com
* palmer@google.com
* richardsmith@google.com
* titus@google.com
- austern@google.com
- chandlerc@google.com
- dmitrig@google.com
- gromer@google.com
- joshl@google.com
- palmer@google.com
- richardsmith@google.com
- titus@google.com
**TODO**: We want this team to eventually include non-Googlers for a broader set
of perspectives.
@@ -165,9 +163,9 @@ There should always be three arbiters.
Our current arbiters are:
* chandlerc@google.com
* richardsmith@google.com
* titus@google.com
- chandlerc@google.com
- richardsmith@google.com
- titus@google.com
### Painter
@@ -189,7 +187,7 @@ aesthetics reasonably consistent.
The current painter is:
* [chandlerc@google.com](mailto:chandlerc@google.com)
- [chandlerc@google.com](mailto:chandlerc@google.com)
### Adding and removing governance members
@@ -205,16 +203,16 @@ 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:
* 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).
- 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).
Changes which generally will not require this process are:
* 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.
- 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 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
@@ -236,23 +234,23 @@ efficient.
##### Actions
* **Author**: Create an `Evolution > Ideas` forum topic to discuss the issue
before writing the proposal.
* **Community**: Provide [constructive commentary](commenting_guidelines.md)
for ideas when feedback is solicited.
- **Author**: Create an `Evolution > Ideas` forum topic to discuss the issue
before writing the proposal.
- **Community**: Provide [constructive commentary](commenting_guidelines.md) for
ideas when feedback is solicited.
#### Make a proposal
The first part of making a proposal is to write up a Google Doc explaining,
roughly in the following order:
* **Problem**: Information about the problem the proposal is trying to solve.
* **Background**: Background on the problem and information needed to
understand the proposed solution.
* **Proposal**: An overview of the solution.
* **Details**: Details of how the proposed solution should be implemented.
* **Alternatives**: Information about alternative solutions or details that
were considered and rejected.
- **Problem**: Information about the problem the proposal is trying to solve.
- **Background**: Background on the problem and information needed to understand
the proposed solution.
- **Proposal**: An overview of the solution.
- **Details**: Details of how the proposed solution should be implemented.
- **Alternatives**: Information about alternative solutions or details that were
considered and rejected.
We use a
[template for proposals](https://docs.google.com/document/d/1sqEnIWWZKTrtMz2XgD7_RqvogwbI0tBQjAZIvOabQsw/template/preview)
@@ -269,8 +267,8 @@ 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
[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.
Where parts of a proposal may have several ways to address them, feel free to
@@ -285,13 +283,12 @@ Where the proposal makes a decision between multiple options, move them to the
##### 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 `WIP`.
- **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
`WIP`.
#### (optional) Elicit early, high-level feedback on the proposal
@@ -301,11 +298,11 @@ favor the forum topic (vs Doc comments) for high-level discussion.
##### Actions
* **Author**: Update (or create if needed) the `Evolution > Ideas` forum topic
to advertise the proposal and elicit early, high-level feedback.
* Add the topic's link to the GitHub issue.
* **Community**: Provide [constructive commentary](commenting_guidelines.md)
for ideas when feedback is solicited.
- **Author**: Update (or create if needed) the `Evolution > Ideas` forum topic
to advertise the proposal and elicit early, high-level feedback.
- Add the topic's link to the GitHub issue.
- **Community**: Provide [constructive commentary](commenting_guidelines.md) for
ideas when feedback is solicited.
### Solicit and address proposal feedback
@@ -321,12 +318,12 @@ 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 GitHub issue.
* Add the topic's link to the GitHub issue.
- **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
GitHub issue.
- Add the topic's link to the GitHub issue.
#### Community and reviewing team comments on proposal
@@ -348,11 +345,11 @@ 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.
* Create GitHub issues for any open questions to be revisited later.
* **Reviewing team and community**: Provide
[constructive commentary](commenting_guidelines.md) for proposals.
- **Author**:
- Update the Doc 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.
#### (optional) Pause for a major revision
@@ -369,19 +366,20 @@ discussion points thus far (with links to those prior topics).
##### Actions
* **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`.
* **Reviewing team and community**: Refrain from commenting until the author
solicits feedback again.
- **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`.
- **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 request a review manager by creating a `Evolution > Review manager
requests` topic. A review manager should respond within a day or two. This may
not be needed if a review manager has already taken ownership.
should request a review manager by creating a
`Evolution > Review manager requests` topic. 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
@@ -393,15 +391,15 @@ the reviewing team will be asked to start making a decision after a day.
##### Actions
* **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.
* 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.
- **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.
- 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.
### Reviewing team makes a proposal decision
@@ -420,10 +418,10 @@ for major revision.
##### 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**:
[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.
#### Ask the reviewing team for a proposal decision
@@ -437,19 +435,19 @@ 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, 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.
* 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 Doc, to ensure they're ready for the meeting.
- 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.
- 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 Doc, 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.
@@ -458,24 +456,23 @@ make decisions.
##### Actions
* **Author**:
* Respond to comments.
* **Review manager:**
* Set both the Google Doc 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
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.
- **Author**:
- Respond to comments.
- **Review manager:**
- Set both the Google Doc 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
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
@@ -491,16 +488,16 @@ 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.
- **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
@@ -520,25 +517,24 @@ author again. It's not necessary to switch ownership back.
##### Actions
* **Review manager**:
* 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
`<decision>`.
* In the Doc history, label the latest revision as `<decision>`.
* 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 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.
- **Review manager**:
- 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
`<decision>`.
- In the Doc history, label the latest revision as `<decision>`.
- 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 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.
#### Community comments on proposal decision
@@ -554,10 +550,10 @@ 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?
- 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 approve the change, the author may start making changes
described in the proposal which are easy to roll back before the decision review
@@ -570,13 +566,12 @@ 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.
- **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
@@ -587,11 +582,11 @@ should be exceptional.
##### Actions
* **Author**: Roll back any dependent changes.
* **Reviewing team member**: State new, non-consensus position on `Evolution >
Decisions` forum topic.
* **Review manager**: Return to
[asking the reviewing team for a proposal decision](#ask-the-reviewing-team-for-a-proposal-decision).
- **Author**: Roll back any dependent changes.
- **Reviewing team member**: State new, non-consensus position on
`Evolution > Decisions` forum topic.
- **Review manager**: Return to
[asking the reviewing team for a proposal decision](#ask-the-reviewing-team-for-a-proposal-decision).
#### Execute on proposal decision
@@ -614,14 +609,13 @@ 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.
* Update the `Evolution > Announcements` forum topic with the final
decision.
* Close the GitHub issue.
* **Author**: Start making dependent changes to apply the proposal.
- **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.
- Update the `Evolution > Announcements` forum topic with the final decision.
- Close the GitHub issue.
- **Author**: Start making dependent changes to apply the proposal.
## Acknowledgements