From 6854266faddafd5bd90003ba629ef70ee012f53d Mon Sep 17 00:00:00 2001 From: Chandler Carruth Date: Mon, 27 Apr 2020 18:57:12 -0700 Subject: [PATCH] Initial commit of main README.md and initial project documents. Subsequent commits should be managed through pull requests. --- CODE_OF_CONDUCT.md | 262 +++++++++ CONTRIBUTING.md | 201 +++++++ README.md | 152 ++++++ docs/README.md | 14 + docs/guides/README.md | 10 + docs/project/README.md | 10 + docs/project/commenting_guidelines.md | 59 ++ docs/project/consensus_decision_making.md | 166 ++++++ docs/project/evolution.md | 631 ++++++++++++++++++++++ docs/project/goals.md | 10 + docs/project/roadmap_process.md | 27 + docs/spec/README.md | 14 + 12 files changed, 1556 insertions(+) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 README.md create mode 100644 docs/README.md create mode 100644 docs/guides/README.md create mode 100644 docs/project/README.md create mode 100644 docs/project/commenting_guidelines.md create mode 100644 docs/project/consensus_decision_making.md create mode 100644 docs/project/evolution.md create mode 100644 docs/project/goals.md create mode 100644 docs/project/roadmap_process.md create mode 100644 docs/spec/README.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000000..d367c12cd2fd --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,262 @@ + + +# Carbon: Code of conduct + +The Carbon community works to be welcoming and respectful, with a deep +commitment to psychological safety, and we want to ensure that doesn’t change as +we grow and evolve. To that end, we have a few ground rules that we ask all +community members to adhere to: + +* be welcoming, +* be friendly and patient, +* be considerate, +* be respectful, +* be careful in the words that you choose and be kind to others, +* when we disagree, try to understand why, and +* recognize when progress has stopped, and take a step back. + +This list isn't exhaustive. Rather, take it in the spirit in which it’s +intended—a guide to make it easier to communicate and participate in the +community. + +This code of conduct applies to all spaces managed by the Carbon project. This +includes chat systems, forums, emails (on lists or between members), issue +trackers, events, and any other spaces that the community uses for +communication. It applies to all of your communication and conduct in these +spaces, including emails, chats, things you say, slides, videos, posters, signs, +or even t-shirts you display in these spaces. In rare cases, violations of this +code _outside_ of these spaces may affect a person’s ability to participate +_within_ these spaces. + +All community members should help support our standards of acceptable behavior. +Everyone is encouraged to speak up in response to any behavior that they deem +inappropriate, threatening, offensive, or harmful. If you believe someone is +violating the code of conduct, please report it to the +[conduct team](#conduct-team). + +More detailed guidance on how to participate effectively in our community +spaces: + +* **Be welcoming.** We strive to be a community that welcomes and supports + people of all backgrounds and identities. This includes, but is not limited + to, members of any race, ethnicity, culture, national origin, color, + immigration status, social and economic class, educational level, sex, + sexual orientation, gender identity and expression, physical appearance, + age, size, family status, relationship status, political belief, religion or + lack thereof, and mental and physical ability. + +* **Be friendly and patient.** We want to encourage people to participate in + our community by keeping its atmosphere friendly and positive. This is + especially important because many of our communication tools on the Internet + are low-fidelity and make it difficult to understand each other. Be patient, + assume good intent, and stay supportive so that we can learn how to + collaborate effectively as a group. + +* **Be considerate.** Your work will be used by other people, and you in turn + will depend on the work of others. Any decision you make will affect users + and colleagues, and you should take those consequences into account. + Remember that we’re a world-wide community, so you might not be + communicating in someone else’s primary language. + +* **Be respectful.** Not all of us will agree all the time, but disagreement + is no excuse for poor behavior and poor manners. We might all experience + some frustration now and then, but we cannot allow that frustration to turn + into a personal attack. It’s important to remember that a community where + people feel uncomfortable or threatened is not a productive one. Members of + our community should be respectful when dealing with other members as well + as with people outside the Carbon community. + +* **Be careful in the words that you choose and be kind to others.** Do not + insult or put down other participants. Harassment and other exclusionary + behaviors aren’t acceptable. This includes, but is not limited to: + + * Violent threats or language directed against another person. + * Discriminatory jokes and language. + * Posting sexually explicit or violent material. + * Posting (or threatening to post) other people’s personally identifying + information ("doxing") without their explicit permission. + * Personal insults, especially those using racist or sexist terms. + * Unwelcome sexual attention. + * Advocating for, or encouraging, any of the above behavior. + * In general, if someone asks you to stop, then stop. Persisting after + being asked to stop is considered harassment. + +* **When we disagree, try to understand why.** Disagreements, both social and + technical, happen all the time, and Carbon is no exception. It is important + that we resolve disagreements and differing views constructively. Remember + that we’re different. The strength of the project comes from its varied + community: people from a wide range of backgrounds. Different people have + different perspectives on issues. Being unable to understand why someone + holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that it is + human to err and blaming each other doesn’t get us anywhere. Instead, focus + on helping to resolve issues and learning from mistakes. + +* **Recognize when progress has stopped, and take a step back.** Regardless of + whether you're trying to resolve a disagreement or anything else, think + about whether you're making progress. Sometimes messaging doesn't give time + to think about a situation fully, and repeating positions can make people + defensive. Step back for a few minutes or hours to think through the issue + before responding again. Consider pulling in another community member to + give a fresh perspective. Maybe meet over VC instead. Switching approaches + can help resume progress. + +If you have questions, please feel free to ask on our Discourse Forum, Discord +Chat, or contact any member of the conduct team directly. + +# Conduct team + +At present, the [core team](docs/project/evolution.md#core-team) will serve as +the conduct team. We expect to establish a dedicated conduct team if and when +the project grows, along with more communication systems for reports. + +## Reporting conduct + +If you believe someone is violating the code of conduct, you can always report +it to the conduct team by emailing all members of the conduct team. **All +reports will be kept confidential.** + +If your report concerns a member of the conduct team, you can make a report +directly to any individual member of the conduct team. They will follow the +usual enforcement process with the other members of the conduct team, but will +exclude the member(s) that the report concerns from any discussion or decision +making. + +If you believe anyone is in **physical danger**, please notify appropriate law +enforcement first. If you are unsure what law enforcement agency is appropriate, +please include this in your report and we will attempt to notify them. + +If the violation occurs at an event and requires immediate attention, you can +also reach out to any of the event organizers or staff. Event organizers and +staff will be prepared to handle the incident and be able to help. If you cannot +find one of the organizers, the venue staff can locate one for you. Specific +event information will include detailed contact information for that event. In +person reports will still be kept confidential exactly as above, but also feel +free to (anonymously if needed) email the conduct team. + +## Filing a report + +Reports can be as formal or informal as needed for the situation at hand. If +possible, please include as much information as you can. If you feel +comfortable, please consider including: + +* Your contact info (so we can get in touch with you if we need to follow up). +* Names (real, nicknames, or pseudonyms) of any individuals involved. If there + were other witnesses besides you, please try to include them as well. +* When and where the incident occurred. Please be as specific as possible. +* Your account of what occurred, including any private chat logs or email. +* Links for any public records, e.g., Discourse Forum links. +* Any extra context for the incident. +* If you believe this incident is ongoing. +* Any other information you believe we should have. + +## What happens after contacting the conduct team? + +You will receive a reply from the conduct team acknowledging receipt within 1 +business day (and we will aim to respond much quicker than that). + +The conduct team will review the incident as soon as possible and try to +determine: + +* What happened and who was involved. +* Whether this event constitutes a code of conduct violation. +* Whether this is an ongoing situation, or if there is a threat to anyone’s + physical safety. + +If this is determined to be an ongoing incident or a threat to physical safety, +the conduct team's immediate priority will be to protect everyone involved. This +means we may delay an "official" response until we believe that the situation +has ended and that everyone is physically safe. + +The conduct team will try to contact other parties involved or witnessing the +event to gain clarity on what happened and understand any different +perspectives. + +Once the conduct team has a complete account of the events they will make a +decision as to how to respond. Responses may include: + +* Nothing, if no violation occurred or it has already been appropriately + resolved. +* One or more [enforcement actions](#enforcement-actions). +* Involvement of relevant law enforcement if appropriate. + +If the situation is not resolved within one week, we’ll respond to the original +reporter with an update and explanation. + +Once we’ve determined our response, we will separately contact the original +reporter and other individuals to let them know what actions (if any) we’ll be +taking. We will take into account feedback from the individuals involved on the +appropriateness of our response, but we don’t guarantee we’ll act on it. + +After any incident, the conduct team will make a report on the situation to the +core team (currently the same team). The core team may choose to make a public +statement about the incident. If that’s the case, the identities of anyone +involved will remain confidential unless instructed otherwise by those +individuals. + +## Appealing + +Only permanent resolutions (such as bans) or requests for public actions may be +appealed. To appeal a decision of the conduct team, contact the +[arbiters](docs/project/evolution.md#arbiters) with your appeal and the arbiters +will review the case. + +In general, it is **not** appropriate to appeal a particular decision in public +areas of Discourse Forums or Discord Chat. Doing so would involve disclosure of +information which should remain confidential. Disclosing this kind of +information publicly may be considered a separate and (potentially) more serious +violation of the Code of Conduct. This is not meant to limit discussion of the +Code of Conduct, the conduct team itself, or the appropriateness of responses in +general, but **please** refrain from mentioning specific facts about cases +without the explicit permission of all parties involved. + +# Enforcement action guidelines + +The conduct team, moderators, and event organizers have the right and +responsibility to remove, edit, or reject comments, commits, code, wiki edits, +issues, and other contributions that are not aligned to this Code of Conduct. +They will communicate reasons for moderation decisions when appropriate. + +The conduct team may take additional action they deem appropriate for any +violation of this Code of Conduct using these guidelines based on the behavior +involved: + +1. **Correction** + * **Behavior:** Use of inappropriate language or other minor violations + the code of conduct. + * **Action:** A private, written message providing clarity around the + nature of the violation and an explanation of why the behavior was + inappropriate. A public apology may be requested. +1. **Warning** + * **Behavior:** A code of conduct violation through a single moderate + incident, or a series of minor violations. + * **Action:** In addition to the correction action, a temporary + restriction barring interaction with the people involved for a specified + period of time, including unsolicited interaction with the conduct team. + Violating these terms may lead to a ban. +1. **Temporary ban** + * **Behavior:** A serious violation of the code of conduct, including + sustained inappropriate behavior. + * **Action:** In addition to the warning action, a temporary ban from use + of Carbon's community spaces for a specified period of time. External + channels (e.g., social media) should not be used to bypass these + restrictions during the temporary ban. Violating these terms may lead to + a permanent ban. +1. **Permanent ban** + * **Behavior:** Demonstrating a pattern of violation of the code of + conduct. + * **Action:** A permanent ban from use of Carbon's community spaces. + +# Acknowledgements + +This code is based on the +[LLVM Code of Conduct](https://llvm.org/docs/CodeOfConduct.html), the +[Django Project Code of Conduct](https://github.com/django/code-of-conduct), the +[Speak Up! project](http://web.archive.org/web/20141109123859/http://speakup.io/coc.html), +and the +[Contributor Covenant version 2.0](https://www.contributor-covenant.org/version/2/0/code_of_conduct/). +Many thanks to all of these projects for their work helping build effective +tools for open source communities. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000000..a0ab5680c61d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,201 @@ + + +# Carbon: Contributing + +Thank you for your interest in contributing to Carbon! There are many ways to +contribute, and we appreciate all of them. If you have questions, please feel +free to ask on our Discourse Forums or Discord Chat. + +Everyone contributing to Carbon is expected to: + +* Read and follow the [Code of Conduct](CODE_OF_CONDUCT.md). We expect + everyone in our community to be welcoming, helpful, and respectful. +* Ensure you have signed the + [Contributor License Agreement (CLA)](https://cla.developers.google.com/). + We need this to cover some legal bases. + +We also encourage anyone interested in contributing to check out all the +information here in our contributing guide, especially the +[guidelines and philosophy for contributions](#guidelines-and-philosophy-for-contributions) + +# Ways to contribute + +## Help comment on proposals + +If you're looking for a quick way to contribute, commenting on proposals is a +way to provide proposal authors with a breadth of feedback. The "Evolution > +Ideas" forum is where authors will go for early, high-level feedback. The +"Evolution > Proposal reviews" forum will have more mature proposals that are +nearing the decision process. For more about the difference, see the +[evolution process](docs/project/evolution.md). + +When giving feedback, please keep comments positive and constructive. Our goal +is to use community discussion to improve proposals and assist authors. + +## Help contribute ideas to Carbon + +If you have ideas for Carbon, we encourage you to discuss it with the community, +and potentially prepare a proposal for it. Ultimately, any changes or +improvements to Carbon will need to turn into a proposal and go through our +[evolution process](docs/project/evolution.md). + +If you do start working on a proposal, keep in mind that this requires a time +investment to discuss the idea with the community, get it reviewed, and +eventually implemented. A good starting point is to read through the +[evolution process](docs/project/evolution.md). We encourage discussing the idea +early, before even writing a proposal, and the process explains how to do that. + +## Help implement Carbon's design + +Eventually, we will also be working toward a reference implementation of Carbon, +and are very interested in folks joining in to help us with it. + +## Help address bugs + +As Carbon's design (and eventually implementation) begin to take shape, we'll +inevitably end up with plenty of bugs. Helping us triage, analyze, and address +them is always a great way to get involved. When we have the bug tracker(s) set +up for this, we'll update this section with ideas of how to find these and get +started. + +# How to become a contributor to Carbon + +## Contributor License Agreements (CLAs) + +We'd love to accept your documentation, pull requests, and comments! Before we +can accept them, we need you to cover some legal bases. + +Please fill out either the individual or corporate CLA. + +* If you are an individual contributing to spec discussions or writing + original source code and you're sure you own the intellectual property, then + you'll need to sign an + [individual CLA](https://code.google.com/legal/individual-cla-v1.0.html). +* If you work for a company that wants to allow you to contribute your work, + then you'll need to sign a + [corporate CLA](https://code.google.com/legal/corporate-cla-v1.0.html). + +Follow either of the two links above to access the appropriate CLA and +instructions for how to sign and return it. Once we receive it, we'll be able to +accept your documents, comments and pull requests. + +**_NOTE_**: Only original content from you and other people who have signed the +CLA can be accepted as Carbon contributions: this covers the GitHub repository, +GitHub issues Google Docs, Discourse Forums and Discord Chat. + +### Future CLA plans + +At present, we are using Google's CLA. In the future, we expect the Carbon +ownership and IP to formally transfer from Google to a Carbon-specific +foundation or other neutral third-party. When that happens, the foundation will +take ownership of providing a CLA. + +## Contribution guidelines and standards + +All documents and pull requests must be consistent with the guidelines and +follow the Carbon documentation and coding styles. + +### Guidelines and philosophy for contributions + +* For **both** documentation and code: + + * When the Carbon team accepts new documentation or features, to Carbon, + by default they take on the maintenance burden. This means they'll weigh + the benefit of each contribution must be weighed against the cost of + maintaining it. + * The appropriate [style](#style) is applied. + * The [license](#license) is present in all contributions. + +* For documentation: + + * All documentation is written for clarity and readability. Beyond fixing + spelling and grammar, this also means content is worded to be accessible + to a broad audience. + * Substantive changes to Carbon follow the + [evolution process](docs/project/evolution.md). Pull requests are only + sent after the documentation changes have been accepted by the reviewing + team. + * Typos or other minor fixes that don't change the meaning of a document + do not need formal review, and are often handled directly as a pull + request. + +* For code: + + * New features should have a documented design that has been approved + through the [evolution process](docs/project/evolution.md). This + includes modifications to pre-existing designs. + * Bug fixes and mechanical improvements don't need this. + * All new features include unit tests, as they help to (a) document and + validate concrete usage of the feature and its edge cases, and (b) guard + against future breaking changes to lower the maintenance cost. + * Bug fixes also generally include unit tests, because the presence of + bugs usually indicates insufficient test coverage. + * Unit tests must pass with the changes. + * If some tests fail for unrelated reasons, we wait until they're fixed + (it helps to contribute a fix!). + * Code changes are made with API compatibility and evolvability in mind. + Reviewers will comment on any API compatibility issues. + * Keep in mind that code contribution guidelines are incomplete while we + start work on Carbon, and may change later. + +# Style + +## Google Docs and Markdown + +Changes to Carbon documentation follow the +[Google developer documentation style guide](https://developers.google.com/style). + +Markdown files additionally follow the +[Google Markdown style guide](https://github.com/google/styleguide/blob/gh-pages/docguide/style.md). + +Other style points to be aware of are: + +* Always say "Discourse Forum" and "Discord Chat" to avoid confusion between + systems. + +## Other files + +If you're not sure what style to use, please ask on Discourse Forums. + +# License + +A license is required at the top of all documents and files. + +## Google Docs + +Google Docs all use this template. It puts the license at the top of every page +if printed. + +TODO: Add link for "this template". + +## Markdown + +Markdown files always have at the top: + +``` + +``` + +TODO: Add an example link when we have one. + +## Other files + +Every file type uses a variation on the same license text ("Apache-2.0 WITH +LLVM-exception") with similar formatting. If you're not sure what text to use, +please ask on Discourse Forums. + +# Acknowledgements + +Carbon's Contributing guidelines are based on +[Tensorflow](https://github.com/tensorflow/tensorflow/blob/master/CONTRIBUTING.md) +and [Flutter](https://github.com/flutter/flutter/blob/master/CONTRIBUTING.md) +guidelines. Many thanks to these communities for their help in providing a +basis. diff --git a/README.md b/README.md new file mode 100644 index 000000000000..8951579fb0c1 --- /dev/null +++ b/README.md @@ -0,0 +1,152 @@ + + +For more information, see [our goals](docs/project/goals.md). + +# Carbon repository overview + +The Carbon Language project is an **_experiment_** to explore a possible, +distant future for the C++ programming language. + +Carbon's main repositories are: + +* carbon-lang - Carbon language specification and documentation. +* carbon-toolchain - Carbon language toolchain and reference implementation. +* carbon-proposals - An archive of reviewed Carbon language proposals. + +# Carbon language + +The Carbon Language project is an **_experiment_** to explore a possible, +distant future for the C++ programming language. It is designed around a +specific set of goals, priorities, and use cases: + +1. Performance-critical software +2. Both software and language evolution +3. Code that is easy to read, understand, and write +4. Practical safety guarantees and testing mechanisms +5. Fast and scalable development +6. Current hardware architectures, OS platforms, and environments as they + evolve +7. Interoperability with and migration from existing C++ code + +The first six of these represent a set of priorities for C++ shared by a +significant subset of the C++ community, industry, and ecosystem. However, C++ +is increasingly constrained by a diverse set of concerns and priorities +(including some that are irrelevant to or in opposition to these goals, such as +ABI stability), and carries a significant historical legacy that makes it +challenging to evolve effectively. The result is that these users struggle to +meet our goals using C++ today, and that is unlikely to change in the near +future. Carbon is an attempt to explore what it would look like to rapidly and +systematically re-engineer C++ into a near optimal future state along the top +six priorities, which nonetheless is still reachable through interoperability, +tooling, automation, and incremental large-scale migration efforts. + +For more information, see docs/process/goals.md. + +### What about other languages? + +Other programming languages don't _currently_ address these needs effectively. +They present interoperability, migration, and performance challenges that make +it expensive and potentially impossible to migrate a large C++ code base. An +approach which requires rewriting an entire binary at once would be infeasible. +A large-scale migration must be incremental, meaning that interoperability and +tool-assisted code rewrites are critical. + +There are projects for several languages to reduce obstacles affecting migration +from C++. Some contributors to Carbon are also contributing to those efforts in +parallel in order to understand all of the options in this space. TODO: write up +a detailed analysis of these languages specifically through the lens of the +above goals. + +One especially interesting aspect not addressed by the active and widely used +languages that might serve this purpose is that they have not been designed +specifically to enable migration from and interoperability with _today's_ C++. +They don't build on top of C++'s _existing_ ecosystem. There are only a few +significant examples of programming languages that center around incremental +migration of large existing codebases. They are specifically designed to not +require complete rewrites, new programming models, or building an entire new +stack/ecosystem. However, there is no comparable option for C++ today: + +* JavaScript → TypeScript +* Java → Kotlin +* C++ → **???** + +Carbon explores what it would look like to fill this gap and align it with the +above priorities. + +### Project status + +**The project is just getting started.** Everything is at a very early stage. If +you are hoping to see lots of concrete ideas and plans, you'll probably want to +check back in 6 months to a year. At this stage, we're just beginning to lay the +foundations. + +It is important to understand that **this is a science experiment**, not a +production effort. There are several initial questions that we want to explore +and answer with this experiment: + +* Can we deliver a design and implementation that is familiar and compelling + to C++ programmers and supports our goals? +* How seamless and effective can we make interoperability? +* How easy and scalable can we make migration? +* Will a significant segment of the ecosystem and industry adopt Carbon given + these tradeoffs? + +We are committed to learning the answers to these questions, but that may well +not result in a production language. There is a very real chance that this +project will never leave the experimental phase. Anyone considering contributing +or using Carbon should be extremely mindful of that fact: **core contributors +may abandon the experiment**. + +While we may sometimes refer to Carbon as a language, it is crucial to +understand that the goals of this science experiment are not about new +languages, but about how to move today's C++ forward effectively. For example, a +near optimal outcome would be to convince the C++ community to adopt this as its +official path forward. + +### What will make Carbon a compelling future path for C++? + +We hope that eventually Carbon will provide **significant advantages compared to +today's C++**. Areas where we think we can most dramatically improve C++ for +both software systems and developers are: + +* A cohesive and principled language design, even when supporting advanced + features. +* Making common coding patterns safe by default whenever practical, with + affordable security mitigations available for any unsafety. + * We will provide static checks for as many safety issues as we can by + default. + * We will provide a spectrum of build modes with different trade-offs + between dynamic safety and performance. For example: + * The default build mode will include as many dynamic safety checks as + we can while keeping the software's performance reasonable for + normal development, testing, and debugging. + * Release builds will favor performance, with opt-in dynamic safety + checks and security mitigations for applications with higher + security requirements. + * Over time, we also expect to both track and drive research into + increasing the degree of safety available without compromising our other + goals. +* Keeping our core language implementation simple, fast, and easily extended + in ways that will make all of our language tools better. +* Providing an effective, open, and inclusive language evolution process + aligned with our goals and priorities. + +Carbon will also aim to allow a single layer of a legacy C++ library stack to be +migrated to Carbon, without migrating the code above or below. This will make it +easier for developers to start using Carbon. Key features underpin Carbon's +compatibility and interoperability with C++: + +* The memory, execution, and threading model will be compatible with C++. +* Access to existing C++ types, interfaces, and even templates will be + provided as part of the core language. +* Carbon will be able to export types, interfaces, and templates for + consumption by C++. + +**However, Carbon's approach still requires a nearly complete re-engineering of +the language as well as large-scale migration for users.** This is extremely +expensive, and so the bar for Carbon to be a compelling direction for C++ is +very high. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000000..4547b1903a9b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,14 @@ + + +# Carbon: Docs + +This directory contains current, accepted documentation underpinning Carbon. +These documents cover all aspects of Carbon ranging from the project down to +detailed designs for specific language features. + +If you're trying to learn more about Carbon, we recommend starting at +/README.md. diff --git a/docs/guides/README.md b/docs/guides/README.md new file mode 100644 index 000000000000..a275587c0b42 --- /dev/null +++ b/docs/guides/README.md @@ -0,0 +1,10 @@ + + +# Carbon: Guides + +This directory contains end user documentation on how to use Carbon. These +should be focused on people trying to use and write code in Carbon. diff --git a/docs/project/README.md b/docs/project/README.md new file mode 100644 index 000000000000..67ed9bc0676a --- /dev/null +++ b/docs/project/README.md @@ -0,0 +1,10 @@ + + +# Carbon: Project + +This directory contains project-related documentation for Carbon. Information +about how the project works, goals and community information belong here. diff --git a/docs/project/commenting_guidelines.md b/docs/project/commenting_guidelines.md new file mode 100644 index 000000000000..49e73570456b --- /dev/null +++ b/docs/project/commenting_guidelines.md @@ -0,0 +1,59 @@ + + +# Carbon: Commenting guidelines + +These commenting guidelines are complementary to the +[evolution process](evolution.md). The community comments on proposals when the +proposal's status is "RFC", providing both positive and critical feedback. We +always try to keep feedback, even when critical, constructive and supportive. + +## Guidelines + +* **Comments should be specific about the issue.** They should include a + suggested action, and the expected result from that action. The more + specific a comment is, the easier it will be for the proposal author to + evaluate. + + * 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 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. + * If your comment represents a significant change to the doc, include a + list of pros and cons. Even if the author disagrees with the change, + they can use those to document the alternative. + +* **Be supportive in your criticism.** The author may be receiving many + comments, and we want to keep contributors motivated to respond. + +* **Be thoughtful about interactions.** Keep the + [code of conduct](/CODE_OF_CONDUCT.md) in mind. Try to understand + disagreements, and if you can't make progress, step back and think about + other possible approaches. + +* **Compliment the author when you're happy with a proposal.** Especially on + the Discourse Forum topics where others will see the feedback. This helps + all of us avoid _only_ focusing on how proposals should improve. We want to + balance that important feedback with explicit and positive feedback for all + the good aspects. + +When commenting on a proposal, some questions community members might want to +address are: + +* What is your evaluation of the proposal? +* Is the problem being addressed significant enough to warrant a change to + Carbon? +* Does this proposal fit with Carbon's + [goals, priorities, and principles](goals.md)? +* Are there alternative approaches that may be better suited to the problem? +* If you have used other languages or libraries with a similar feature, how + does the proposal compare? diff --git a/docs/project/consensus_decision_making.md b/docs/project/consensus_decision_making.md new file mode 100644 index 000000000000..94fe099b1303 --- /dev/null +++ b/docs/project/consensus_decision_making.md @@ -0,0 +1,166 @@ + + +# Carbon: Consensus decision-making + +Carbon's teams will use a +[blocking consensus decision-making process](https://en.wikipedia.org/wiki/Consensus_decision-making#Blocking) +to make decisions on proposals. We want all voices to be heard; we expect to +iterate, identify and address concerns in order to reach consensus. A decision +is approved when there is full agreement, although some team members may +actively choose to stand aside. + +We expect most decisions to be made in public, although some exceptional +decisions will be private if a team member requests it. In any case, it's +expected that only the reviewing team will actively participate in consensus +discussions. + +## Main consensus process + +Any team member involved in a decision may object and break consensus. +Dissenters should present their concerns, ideally with proposed fixes. Another +round of discussion may occur in order to address concerns. The goal is to +ensure that team members are empowered to surface narrow but critical concerns +that may only be noticed by a minority. + +Team members have a fundamentally different role while working towards consensus +on a decision than at other times on the project. They are expected to: + +* Set aside personal advocacy and preferences, and focus on the best decision + for the project and community. +* Critically evaluate whether their concerns are severe enough to warrant + blocking. +* Focus on the information presented in a proposal, rather than adding new + information. If new information is needed, the request for it should be the + decision. +* Recognize their own biases and stand aside when unable to form an objective + position. + +More about consensus decision making may be found from +"[On Conflict and Consensus](https://web.archive.org/web/20111026234752/http://www.ic.org/pnp/ocac/)", +and https://www.consensusdecisionmaking.org/. + +## Formal decision content + +A formal decision consists of: + +* The decision itself. +* A summary of the decision rationale. +* A summary of important discussion points. + +Here are some possible decisions with their meanings: + +* **accepted**: Yes, we want this now. +* **declined**: No, we don't think this is the right direction for Carbon. +* **needs work**: + * We need more information or data before we can decide if this is the + right direction. + * We like the direction, but the proposal needs significant changes before + being accepted. +* **deferred**: + * We like the direction, but it isn't our priority right now, so bring the + proposal back later. + * We aren't sure about the direction, but it isn't our priority right now, + so bring it back later. + +When a proposal has open questions, the formal decision must include a decision +for each open question. That may include filing GitHub issues to revisit the +open questions later. + +Each decision should have a rationale based on Carbon's +[goals, priorities, and principles](goals.md). When the rationale requires +explanation, the application of these goals should be documented. The reviewing +team should check any relevant prior decisions and update or resolve +inconsistencies in order to have a clear and consistent application of Carbon's +goals. + +At times, the goals, priorities and principles will simply not cover or provide +a way to make a decision. In that case, the reviewing team is expected to shift +the discussion to start with adjusting the goals, priorities and principles to +cover the new context and questions. This should then be the first decision they +have to make, and the technical decision should only be made afterward, so that +it can cite the now pertinent goals, priorities and principles. + +## Meetings + +In order to ensure we can rapidly make decisions, each team will have a standing +weekly meeting slot, which observers may attend. Members are expected to do +their best to keep the slot available. Meetings will be held using Google +Hangouts Meet. + +Each time a team needs to make a decision, e.g., about a change to Carbon, it is +expected that we'll try to make a decision without using a live meeting. We will +only hold meetings when decisions cannot be resolved before the meeting. + +### Agenda + +An agenda will be maintained for upcoming meetings. If there are no agenda +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. + +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 +any presentation or summary. Discussion will go over the proposal's agenda item +and sub-items, with each agenda item resolving with a decision. + +### Roles + +As part of organizing a meeting, we will have two roles: + +* A **moderator** who is responsible for ensuring discussion stays on track. +* A **note taker** who will record minutes for each meeting. + +Roles should be known before each meeting. These may or may not be staffed by +reviewing team members; anybody taking a role should plan to be less involved in +discussion in order to focus on their role. The roles should be handled by +different people. + +During the meeting, the moderator is responsible for ensuring we move in an +orderly fashion from topic to topic. Meetings will have a Discord Chat that the +moderator will watch. Attendees should let the moderator know whether they want +to speak to the current topic or a new topic, and will be added to the +appropriate queue. When it's the next person's turn to speak, the moderator will +indicate whose turn it is. If there are few enough active participants, we may +choose to skip the queue for a meeting. + +The moderator is also responsible for ensuring discussions stay on track. Only +the moderator should interrupt speakers or speak outside the queue, and the +moderator _should_ do so if discussion isn't progressing. The moderator is also +responsible for polling for consensus on decisions during the meeting. + +All team members should keep in mind that the ultimate goal of each meeting is a +decision, and to consider what they discuss during a meeting in keeping with +that goal. + +There may be multiple review managers in a meeting, depending on the number of +proposals being reviewed. Each needs to make sure they know decision information +for the proposal they're managing when the meeting ends. + +### Observers + +While community members outside of the team may attend meetings, they are +expected to be passive observers. They should only speak if prompted by a member +of the team (e.g., asking a question to a proposal author). Community discussion +belongs on forums, and the meetings are for team discussions and decisions. + +## Unavailable team members + +If a team member is asked for a pre-meeting decision and hasn't responded by two +working days before the meeting, the team may assume they're unavailable and +standing aside. The intent is to avoid unnecessary meetings. Not responding is +strongly discouraged; please respond if you want the meeting. + +Team members are encouraged to notify others when they're on vacation or +otherwise unavailable for a while, and add it to the shared calendar. Members +are also encouraged to stand aside from decisions if unavailable for more than +half a week. If they have a specific interest in a topic or decision, they may +ask for a delay while they're out. diff --git a/docs/project/evolution.md b/docs/project/evolution.md new file mode 100644 index 000000000000..e42a048e20c3 --- /dev/null +++ b/docs/project/evolution.md @@ -0,0 +1,631 @@ + + +# Carbon: Governance and Evolution + +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. + +## Governance Structure + +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. + +## Evolution process + +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). + +The process is: + +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) + +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) + +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) + +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) + +## Coordination Tools + +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. + +## Governance structure + +### Review managers + +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 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. + +Our current review managers are: + +* [jperkins@google.com](mailto:jperkins@google.com) +* [shummert@google.com](mailto:shummert@google.com) + +### Core team + +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). + +The team is expected to remain relatively small for efficiency, although members +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 + +**TODO**: We want this team to eventually include non-Googlers for a broader set +of perspectives. + +#### Subteams + +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. + +### Arbiters + +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. + +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 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. + +Arbiters may make a decision with a majority (two-to-one) vote. If they cannot +reach a majority vote, e.g. due to an arbiter being unavailable, the decision +returns to the core team. + +There should always be three arbiters. + +Our current arbiters are: + +* chandlerc@google.com +* richardsmith@google.com +* titus@google.com + +### Painter + +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. + +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. + +The painter is a single person in order to keep decisions around taste or +aesthetics reasonably consistent. + +The current painter is: + +* [chandlerc@google.com](mailto:chandlerc@google.com) + +### Adding and removing governance members + +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. + +## Evolution process + +### When to follow the evolution process + +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). + +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. + +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. + +### Draft the proposal + +#### (optional) Discuss the idea early + +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. + +These discussions can also help socialize both the problem and ideas with the +community, making subsequent discussions around a concrete proposal more +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. + +#### 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. + +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. + +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. + +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. + +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. + +##### 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`. + +#### (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. + +##### 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. + +### Solicit and address proposal feedback + +#### Request comments + +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. + +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 GitHub issue. + * Add the topic's link to the GitHub issue. + +#### Community and reviewing team comments on proposal + +Anyone in the community is welcome to +[respond on an RFC](commenting_guidelines.md). The reviewing team is _expected_ +to participate at least enough to provide any relevant feedback. + +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. + +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 pros and cons either way. New "open questions" may +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. + +#### (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 (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. + +#### 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. + +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. + +If the proposal is ready, the review manager will put out a last call for +community comments on the main discussion topic. If nothing significant arises, +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. + +### 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. + +##### 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. + +#### 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` forum topic asking for consensus. The proposal +should also be added as a topic to the team's meeting agenda one week in advance +(or four working days, if 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, 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. +If no decision can be reached before the meeting, the meeting will be used to +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. + +#### (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 relevant) the meeting notes. They should +prepare a pull request with a PDF of the proposal for reference of what was +approved. They will post the draft decision to the `Evolution > Announcements` +forum within two working days. The post will start the proposal decision comment +period. + +In some cases, the proposal may end up going back to the author for additional +changes. In these cases, the review manager should grant edit access to the +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 + ``. + * In the Doc history, label the latest revision as ``. + * 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 + +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 approve the change, 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, e.g. 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 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 + +When the comment period ends without objections from the reviewing team, the +review manager should finalize the decision (approved, rejected, deferred, +etc.). The review manager should commit the proposal PDF for archival purposes. + +If the decision is to approve the change, the author may make the changes +described in the proposal. There may still be review comments, but those should +exclusively deal with the **document** (formatting, structure, links, etc.), and +not the proposal. The issue should **not** be re-argued on the pull request or +other code reviews. + +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**: + * 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 + +Our governance and evolution process is influenced by the +[Rust](https://github.com/rust-lang/rfcs), +[Swift](https://swift.org/contributing/), and C++ processes. Many thanks to +these communities for providing a basis. diff --git a/docs/project/goals.md b/docs/project/goals.md new file mode 100644 index 000000000000..4046a76f75ff --- /dev/null +++ b/docs/project/goals.md @@ -0,0 +1,10 @@ + + +# Carbon: Goals + +This is a placeholder. See the +[pending proposal](https://docs.google.com/document/d/1MJvVIDXQrhIj6hZ7NwMDbDch9XLO2VaYrGq29E57meU/edit). diff --git a/docs/project/roadmap_process.md b/docs/project/roadmap_process.md new file mode 100644 index 000000000000..e95fbc9da882 --- /dev/null +++ b/docs/project/roadmap_process.md @@ -0,0 +1,27 @@ + + +# Carbon: Roadmap process + +Carbon has an annual roadmap to align and focus the work of the teams and +community. Teams will need to defer work on Carbon that may be good and make +sense but doesn't align with the current focus and plan of the project. + +The core team will draft proposed roadmaps each year, going through the standard +proposal review process. It is expected that the core team will provide a draft +decision and enter decision review first thing at the beginning of the year, +concluding in an accepted plan of record for the overarching direction of the +project for that year. Subteams may optionally follow a similar practice as +needed for their area of Carbon. + +This roadmap is not strictly binding and does not need to cover everything that +will happen. However, it can and should be used by teams to defer some proposals +as needed to focus on proposals aligned with the current roadmap. + +The roadmap is also subject to change, just as any other document, with a fresh +proposal. The core team should critically evaluate the direction and any new +information on a quarterly basis during the initial phase of the project and +adjust the roadmap as needed to stay focused on the most important things. diff --git a/docs/spec/README.md b/docs/spec/README.md new file mode 100644 index 000000000000..11629797cfd4 --- /dev/null +++ b/docs/spec/README.md @@ -0,0 +1,14 @@ + + +# Carbon: Spec + +Eventually, this will be the home of a formal specification for the Carbon +Language. We are committed to having a specification that is sufficiently +detailed to allow independent implementations of the language. While we plan to +have a reference implementation, we think having a specification as well is an +important tool to ensure that the behavior of the language is well understood +and holds together.