diff --git a/.prettierrc b/.prettierrc deleted file mode 100644 index 1dee9acd13b8..000000000000 --- a/.prettierrc +++ /dev/null @@ -1,5 +0,0 @@ -printWidth: 80 -proseWrap: "always" -singleQuote: true -tabWidth: 2 -useTabs: false diff --git a/.prettierrc.yaml b/.prettierrc.yaml new file mode 100644 index 000000000000..dbbbf5400154 --- /dev/null +++ b/.prettierrc.yaml @@ -0,0 +1,10 @@ +printWidth: 80 +proseWrap: 'always' +singleQuote: true +tabWidth: 2 +trailingComma: 'es5' +useTabs: false +overrides: + - files: '*.md' + options: + tabWidth: 4 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 527a0d71976d..68cef4bcb6ee 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -11,13 +11,13 @@ commitment to psychological safety, and we want to ensure that doesn’t change 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. +- 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. @@ -40,68 +40,68 @@ violating the code of conduct, please report it to the 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 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 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 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 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: +- **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. + - 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. +- **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. +- **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. @@ -142,15 +142,15 @@ 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, including Discourse Forum links. -- Any extra context for the incident. -- If you believe this incident is ongoing. -- Any other information you believe we should have. +- 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, including 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? @@ -160,10 +160,10 @@ 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. +- 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 @@ -177,10 +177,10 @@ 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. +- 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. @@ -223,29 +223,30 @@ 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. + - **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. + - **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, such as social media, should not be used to bypass these - restrictions during the temporary ban. Violating these terms may lead to a - permanent 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, such as 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. + - **Behavior:** Demonstrating a pattern of violation of the code of + conduct. + - **Action:** A permanent ban from use of Carbon's community spaces. ## Acknowledgements diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7e262e33810d..27d4f084201e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,11 +12,11 @@ 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. +- 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 @@ -71,13 +71,13 @@ 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). +- 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 @@ -102,41 +102,42 @@ Membership is currently invite-only. Before using these systems, everyone must sign the CLA. They are all governed by the Code of Conduct. -- [The GitHub carbon-language organization](https://github.com/orgs/carbon-language) - is used for our repositories. **To join:** +- [The GitHub carbon-language organization](https://github.com/orgs/carbon-language) + is used for our repositories. **To join:** - 1. Ask [an admin](docs/project/groups.md#admins) to send an invite, providing - your GitHub account. - 2. Check your email to accept the invite, or try the standard - [accept link](https://github.com/orgs/carbon-language/invitation?via_email=1) - if you don't see the email. + 1. Ask [an admin](docs/project/groups.md#admins) to send an invite, + providing your GitHub account. + 2. Check your email to accept the invite, or try the standard + [accept link](https://github.com/orgs/carbon-language/invitation?via_email=1) + if you don't see the email. -- [Discourse Forums](https://forums.carbon-lang.dev) are used for long-form - discussions. **To join:** +- [Discourse Forums](https://forums.carbon-lang.dev) are used for long-form + discussions. **To join:** - 1. Go to [the forums](https://forums.carbon-lang.dev) and register your - GitHub account. - - You will be able to choose which GitHub email you want the forums to - send email to. - 2. [An admin](docs/project/groups.md#admins) will need to approve your - registration. + 1. Go to [the forums](https://forums.carbon-lang.dev) and register your + GitHub account. + - You will be able to choose which GitHub email you want the forums to + send email to. + 2. [An admin](docs/project/groups.md#admins) will need to approve your + registration. -- [Discord Chat](https://discord.com/app) is used for short-form chats. **To - join:** +- [Discord Chat](https://discord.com/app) is used for short-form chats. **To + join:** - 1. Ask [an admin](docs/project/groups.md#admins) for an invite link. - - Please do not re-share the invite links: they're our only way to - restrict access. - 2. You will be prompted with the Code of Conduct. After reading it, click the - check mark reaction icon at the bottom. + 1. Ask [an admin](docs/project/groups.md#admins) for an invite link. + - Please do not re-share the invite links: they're our only way to + restrict access. + 2. You will be prompted with the Code of Conduct. After reading it, click + the check mark reaction icon at the bottom. -- [A shared Google Drive](https://drive.google.com/corp/drive/folders/0ALTu5Y6kc39XUk9PVA) - is used for all of our Google Docs, particularly proposal drafts. **To join:** - 1. Ask [an admin](docs/project/groups.md#admins) to invite you, providing - your Google account email. - 2. The admin will add you to the - [Google Group](https://groups.google.com/g/carbon-lang-contributors) used - for access. +- [A shared Google Drive](https://drive.google.com/corp/drive/folders/0ALTu5Y6kc39XUk9PVA) + is used for all of our Google Docs, particularly proposal drafts. **To + join:** + 1. Ask [an admin](docs/project/groups.md#admins) to invite you, providing + your Google account email. + 2. The admin will add you to the + [Google Group](https://groups.google.com/g/carbon-lang-contributors) + used for access. ### Contribution guidelines and standards @@ -145,44 +146,46 @@ follow the Carbon documentation and coding styles. #### Guidelines and philosophy for contributions -- For **both** documentation and code: +- 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. + - 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: +- 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. + - 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: +- 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. + - 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. ## pre-commit @@ -204,19 +207,19 @@ Markdown files should additionally use Other style points to be aware of are: -- Whereas the Google developer documentation style guide - [says to use an em dash](https://developers.google.com/style/dashes) - (`text—text`), we are using a double-hyphen with surrounding spaces - (`text -- text`). We are doing this because we frequently read Markdown with - fixed-width fonts where em dashes are not clearly visible. -- Always say "Discourse Forum" and "Discord Chat" to avoid confusion between - systems. -- Prefer the term "developers" when talking about people who would write Carbon - code. We expect the Carbon's community to include people who think of - themselves using many titles, including software developers, software - engineers, systems engineers, reliability engineers, data scientists, computer - scientists, programmers, and coders. We're using "developers" to succinctly - cover the variety of titles. +- Whereas the Google developer documentation style guide + [says to use an em dash](https://developers.google.com/style/dashes) + (`text—text`), we are using a double-hyphen with surrounding spaces + (`text -- text`). We are doing this because we frequently read Markdown with + fixed-width fonts where em dashes are not clearly visible. +- Always say "Discourse Forum" and "Discord Chat" to avoid confusion between + systems. +- Prefer the term "developers" when talking about people who would write + Carbon code. We expect the Carbon's community to include people who think of + themselves using many titles, including software developers, software + engineers, systems engineers, reliability engineers, data scientists, + computer scientists, programmers, and coders. We're using "developers" to + succinctly cover the variety of titles. ### Other files diff --git a/README.md b/README.md index 8f5abd1546f7..6f71c7187558 100644 --- a/README.md +++ b/README.md @@ -56,9 +56,9 @@ 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++ → **???** +- JavaScript → TypeScript +- Java → Kotlin +- C++ → **???** Carbon explores what it would look like to fill this gap and align it with the above priorities. @@ -74,12 +74,12 @@ 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? +- 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 @@ -99,37 +99,38 @@ 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. +- 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++. +- 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 @@ -140,5 +141,6 @@ very high. Carbon's main repositories are: -- **carbon-lang** - Carbon language specification and documentation. -- **carbon-toolchain** - Carbon language toolchain and reference implementation. +- **carbon-lang** - Carbon language specification and documentation. +- **carbon-toolchain** - Carbon language toolchain and reference + implementation. diff --git a/docs/project/commenting_guidelines.md b/docs/project/commenting_guidelines.md index 3040d7b74b4e..0737a25e871f 100644 --- a/docs/project/commenting_guidelines.md +++ b/docs/project/commenting_guidelines.md @@ -13,44 +13,45 @@ 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. +- **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. + - Objections to specific phrasing should suggest alternative phrasing. -- **Prefer GitHub for comments.** When reviewing a proposal, we would like to - keep the discussion focused in one place: the GitHub pull request. +- **Prefer GitHub for comments.** When reviewing a proposal, we would like to + keep the discussion focused in one place: the GitHub pull request. - - If your comment represents a significant change to the proposal, include a - list of pros and cons. Even if the author disagrees with the change, they - can use those to document the alternative. - - Feel free to extract long side discussions to a Discourse Forum topic, but - make sure any important conclusions or outcomes are reflected in either the - GitHub comments or the change itself. + - If your comment represents a significant change to the proposal, include + a list of pros and cons. Even if the author disagrees with the change, + they can use those to document the alternative. + - Feel free to extract long side discussions to a Discourse Forum topic, + but make sure any important conclusions or outcomes are reflected in + either the GitHub comments or the change itself. -- **Be supportive in your criticism.** The author may be receiving many - comments, and we want to keep contributors motivated to respond. +- **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. +- **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. +- **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? +- 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 index 3f9d71b8f59f..274ae6f0c599 100644 --- a/docs/project/consensus_decision_making.md +++ b/docs/project/consensus_decision_making.md @@ -29,15 +29,15 @@ 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. +- 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/)", @@ -47,24 +47,24 @@ and https://www.consensusdecisionmaking.org/. A formal decision consists of: -- The decision itself. -- A summary of the decision rationale. -- A summary of important discussion points. +- 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. +- **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 @@ -116,8 +116,8 @@ and sub-items, with each agenda item resolving with a decision. 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. +- 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 diff --git a/docs/project/contribution_tools.md b/docs/project/contribution_tools.md index 2bd256eddf43..66086b4328dd 100644 --- a/docs/project/contribution_tools.md +++ b/docs/project/contribution_tools.md @@ -13,12 +13,12 @@ contributions. -- [pre-commit](#pre-commit) -- [black](#black) -- [codespell](#codespell) -- [markdown-toc](#markdown-toc) -- [Prettier](#prettier) - - [vim-prettier](#vim-prettier) +- [pre-commit](#pre-commit) +- [black](#black) +- [codespell](#codespell) +- [markdown-toc](#markdown-toc) +- [Prettier](#prettier) + - [vim-prettier](#vim-prettier) @@ -30,15 +30,16 @@ important checks, including formatting. To set up pre-commit: -- Follow the [installation instructions](https://pre-commit.com/#installation). -- Enable per-repo: `pre-commit install` - - We already have `pre-commit` configured for Carbon repos -- do not go - through the `Quick start` instructions. -- pre-commit may be run either automatically with `git commit` or manually with - `pre-commit run`. - - When files are modified, including by pre-commit failures, `git add` will - need to be run to include the modifications in the commit, and the commit - re-started. +- Follow the + [installation instructions](https://pre-commit.com/#installation). +- Enable per-repo: `pre-commit install` + - We already have `pre-commit` configured for Carbon repos -- do not go + through the `Quick start` instructions. +- pre-commit may be run either automatically with `git commit` or manually + with `pre-commit run`. + - When files are modified, including by pre-commit failures, `git add` + will need to be run to include the modifications in the commit, and the + commit re-started. When modifying or adding pre-commit hooks, please run `pre-commit run --all-files` to see what changes. @@ -77,16 +78,11 @@ always run Prettier after markdown-toc. > Installing and running manually is optional, but may be helpful. We use [Prettier](https://prettier.io/) for formatting. There is an -[rc file](/.prettierrc) for configuration. +[rc file](/.prettierrc.yaml) for configuration. ### vim-prettier -If you use [vim-prettier](https://github.com/prettier/vim-prettier), it may help -to add to your `.vimrc`: - -``` -let g:prettier#config#print_width = '80' -let g:prettier#config#tab_width = '2' -let g:prettier#config#use_tabs = 'false' -let g:prettier#config#prose_wrap = 'always' -``` +If you use [vim-prettier](https://github.com/prettier/vim-prettier), the +`.prettierrc.yaml` should still apply as long as `config_precedence` is set to +the default `file-override`. However, we may need to add additional settings +where the `vim-prettier` default diverges from `prettier`, as we notice them. diff --git a/docs/project/evolution.md b/docs/project/evolution.md index f16e7cae95d2..38a0aa7bb968 100644 --- a/docs/project/evolution.md +++ b/docs/project/evolution.md @@ -18,14 +18,15 @@ 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 @@ -67,21 +68,22 @@ The process is: We use several tools to coordinate changes to Carbon: -- **GitHub pull requests** contain the proposals and related discussion. - Resolved proposals will be committed with the associated decision. The pull - request's description should link all related Discourse Forum topics and other - references for easy browsing. -- **Discourse Forum** topics will be used for the early idea discussion, any - deeper discussions, or more high-level and meta points. -- **Discord Chat** can be used for quick and real-time chats and Q&A. - - If there are important technical points raised or addressed, they should get - summarized on a relevant Discourse Forum topic. -- **Google Docs** may be used for early draft proposals. This facilitates - collaborative editing and easy commenting about wording issues. -- **Google 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 pull requests** contain the proposals and related discussion. + Resolved proposals will be committed with the associated decision. The pull + request's description should link all related Discourse Forum topics and + other references for easy browsing. +- **Discourse Forum** topics will be used for the early idea discussion, any + deeper discussions, or more high-level and meta points. +- **Discord Chat** can be used for quick and real-time chats and Q&A. + - If there are important technical points raised or addressed, they should + get summarized on a relevant Discourse Forum topic. +- **Google Docs** may be used for early draft proposals. This facilitates + collaborative editing and easy commenting about wording issues. +- **Google 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. ## Governance structure @@ -100,8 +102,8 @@ team will still review participation. Our current review managers are: -- [jonmeow](https://github.com/jonmeow) -- [sidney13](https://github.com/sidney13) +- [jonmeow](https://github.com/jonmeow) +- [sidney13](https://github.com/sidney13) ### Core team @@ -116,14 +118,14 @@ may be added when necessary to expand representation. Our current core team members are: -- [austern](https://github.com/austern) -- [chandlerc](https://github.com/chandlerc) -- [geoffromer](https://github.com/geoffromer) -- [gribozavr](https://github.com/gribozavr) -- [josh11b](https://github.com/josh11b) -- [noncombatant](https://github.com/noncombatant) -- [tituswinters](https://github.com/tituswinters) -- [zygoloid](https://github.com/zygoloid) +- [austern](https://github.com/austern) +- [chandlerc](https://github.com/chandlerc) +- [geoffromer](https://github.com/geoffromer) +- [gribozavr](https://github.com/gribozavr) +- [josh11b](https://github.com/josh11b) +- [noncombatant](https://github.com/noncombatant) +- [tituswinters](https://github.com/tituswinters) +- [zygoloid](https://github.com/zygoloid) **TODO**: We want this team to eventually include non-Googlers for a broader set of perspectives. @@ -163,9 +165,9 @@ There should always be three arbiters. Our current arbiters are: -- [chandlerc](https://github.com/chandlerc) -- [tituswinters](https://github.com/tituswinters) -- [zygoloid](https://github.com/zygoloid) +- [chandlerc](https://github.com/chandlerc) +- [tituswinters](https://github.com/tituswinters) +- [zygoloid](https://github.com/zygoloid) ### Painter @@ -187,7 +189,7 @@ aesthetics reasonably consistent. The current painter is: -- [chandlerc](https://github.com/chandlerc) +- [chandlerc](https://github.com/chandlerc) ### Adding and removing governance members @@ -203,16 +205,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 @@ -234,10 +236,10 @@ 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 @@ -282,9 +284,10 @@ request for the RFC. ##### Actions -- **Author**: - - Write the proposal using [the template](/proposals/template.md). - - The template has additional actions under "TODO: Initial proposal setup". +- **Author**: + - Write the proposal using [the template](/proposals/template.md). + - The template has additional actions under "TODO: Initial proposal + setup". #### (optional) Elicit early, high-level feedback on the proposal @@ -294,11 +297,11 @@ favor GitHub comments over forum topic replies. ##### 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 pull request. -- **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 pull request. +- **Community**: Provide [constructive commentary](commenting_guidelines.md) + for ideas when feedback is solicited. ### Solicit and address proposal feedback @@ -313,11 +316,12 @@ discussion, as well as links to prior discussion topics. ##### Actions -- **Author**: - - Replace the GitHub pull request's `WIP` label with `RFC`. - - Create an `Evolution > RFCs` forum topic. - - Summarize the discussion points, along with a link to the pull request. - - Add the topic's link to the pull request's description. +- **Author**: + - Replace the GitHub pull request's `WIP` label with `RFC`. + - Create an `Evolution > RFCs` forum topic. + - Summarize the discussion points, along with a link to the pull + request. + - Add the topic's link to the pull request's description. #### Community and reviewing team comments on proposal @@ -339,11 +343,11 @@ also be added where the author isn't confident about the best approach. ##### Actions -- **Author**: - - Update the proposal and/or reply to comments to address feedback. - - 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 proposal and/or reply to comments 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 @@ -360,12 +364,12 @@ discussion points thus far. Links to prior topics should be included. ##### Actions -- **Author**: - - Announce to the Discourse Forum topic that the proposal is undergoing major - revision. - - Replace the GitHub pull request's `RFC` label with `WIP`. -- **Reviewing team and community**: Refrain from commenting until the author - solicits feedback again. +- **Author**: + - Announce to the Discourse Forum topic that the proposal is undergoing + major revision. + - Replace the GitHub pull request's `RFC` label with `WIP`. +- **Reviewing team and community**: Refrain from commenting until the author + solicits feedback again. #### Request a review manager @@ -388,15 +392,15 @@ the comment period by posting another message to the "Evolution > RFCs" topic. ##### 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 GitHub pull request. - - Add the topic's link to the GitHub pull request. -- **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 > RFCs` 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 GitHub pull request. + - Add the topic's link to the GitHub pull request. +- **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 > RFCs` topic with a last call for comments. ### Reviewing team makes a proposal decision @@ -410,7 +414,7 @@ making/accepting edits. ##### Actions -- **Author**: Stop making changes to the proposal. +- **Author**: Stop making changes to the proposal. #### Ask the reviewing team for a proposal decision @@ -424,19 +428,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. Standing - aside is allowed. - - Rationales for positions should be based on discussion on the proposal's - `Evolution > RFCs` topic, and providing links helps write the decision. -- A request for more time to review materials, to make it clear the intent is to - participate in the decision. -- Discussion regarding positions or the decision itself. - - The reviewing team will participate in the proposal community comment - period, so that substantive feedback can be incorporated by the author prior - to requesting a decision. -- A request to use the meeting for discussion. - - All topics for discussion will be captured either in the agenda or as a - comment on the pull request, to ensure they're ready for the meeting. +- A position, either affirming or objecting, is strongly preferred. Standing + aside is allowed. + - Rationales for positions should be based on discussion on the proposal's + `Evolution > RFCs` topic, and providing links helps write the decision. +- A request for more time to review materials, to make it clear the intent is + to participate in the decision. +- Discussion regarding positions or the decision itself. + - The reviewing team will participate in the proposal community comment + period, so that substantive feedback can be incorporated by the author + prior to requesting a decision. +- A request to use the meeting for discussion. + - All topics for discussion will be captured either in the agenda or as a + comment on the pull request, to ensure they're ready for the meeting. The review manager should monitor the forum topic for consensus. If a decision is made before the meeting, the item should be removed from the meeting agenda. @@ -445,21 +449,22 @@ make decisions. ##### Actions -- **Author**: - - Respond to comments. -- **Review manager:** - - Replace the GitHub pull request's `RFC` label with `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:** + - Replace the GitHub pull request's `RFC` label with `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 @@ -475,16 +480,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 @@ -502,32 +507,33 @@ continue working on it. ##### Actions -- **Review manager**: - - Write the - [formal decision](consensus_decision_making.md#formal-decision-content), - possibly with help from the reviewing team. - - (optional): Create a GitHub issue for issues that should be revisited in - the future. Link to these from the GitHub pull request. - - If the proposal was accepted: - - Prepare a GitHub pull request with the decision. - - Create an `Evolution > Announcements` forum topic and link to the proposal - and decision pull requests. - - Add the topic's link to the proposal's pull request. - - Approve the proposal's pull request for commit. - - If the proposal was deferred or declined: - - Comment on the proposal's pull request with the decision. - - Create an `Evolution > Announcements` forum topic and link to the proposal - and decision comment. -- **Author**: - - If the proposal is accepted: - - Replace the GitHub pull request's `needs decision` label with `accepted`. - - Commit the approved pull request. - - If the proposal was deferred or declined, decide how best to proceed: - - If iterating on the proposal, replace the GitHub pull request's - `needs decision` label with `WIP`. - - If retracting the proposal, close the pull request. -- **Reviewing team**: Help draft any rationale needed by the review manager for - the decision. +- **Review manager**: + - Write the + [formal decision](consensus_decision_making.md#formal-decision-content), + possibly with help from the reviewing team. + - (optional): Create a GitHub issue for issues that should be + revisited in the future. Link to these from the GitHub pull request. + - If the proposal was accepted: + - Prepare a GitHub pull request with the decision. + - Create an `Evolution > Announcements` forum topic and link to the + proposal and decision pull requests. + - Add the topic's link to the proposal's pull request. + - Approve the proposal's pull request for commit. + - If the proposal was deferred or declined: + - Comment on the proposal's pull request with the decision. + - Create an `Evolution > Announcements` forum topic and link to the + proposal and decision comment. +- **Author**: + - If the proposal is accepted: + - Replace the GitHub pull request's `needs decision` label with + `accepted`. + - Commit the approved pull request. + - If the proposal was deferred or declined, decide how best to proceed: + - If iterating on the proposal, replace the GitHub pull request's + `needs decision` label with `WIP`. + - If retracting the proposal, close the pull request. +- **Reviewing team**: Help draft any rationale needed by the review manager + for the decision. #### Community comments on proposal decision @@ -543,10 +549,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 accept the proposal, the author may start making changes described in the proposal which are easy to roll back before the decision review @@ -559,12 +565,13 @@ 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. +- **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 @@ -575,13 +582,14 @@ should be exceptional. ##### Actions -- **Author**: Roll back the committed proposal and any dependent changes. -- **Reviewing team member**: State new, non-consensus position on - `Evolution > Decisions` forum topic. -- **Review manager**: - - Update the `Evolution > Announcements` forum topic to reflect the rollback. - - Return to - [asking the reviewing team for a proposal decision](#ask-the-reviewing-team-for-a-proposal-decision). +- **Author**: Roll back the committed proposal and any dependent changes. +- **Reviewing team member**: State new, non-consensus position on + `Evolution > Decisions` forum topic. +- **Review manager**: + - Update the `Evolution > Announcements` forum topic to reflect the + rollback. + - Return to + [asking the reviewing team for a proposal decision](#ask-the-reviewing-team-for-a-proposal-decision). #### Execute on proposal decision @@ -602,10 +610,11 @@ revisit the decision. ##### Actions -- **Review manager**: - - Update the `Evolution > Announcements` forum topic with the final decision. - - If the proposal was accepted, commit the proposal decision. -- **Author**: Start making dependent changes to apply the proposal. +- **Review manager**: + - Update the `Evolution > Announcements` forum topic with the final + decision. + - If the proposal was accepted, commit the proposal decision. +- **Author**: Start making dependent changes to apply the proposal. ## Acknowledgements diff --git a/docs/project/goals.md b/docs/project/goals.md index fd32ce9b421f..da2cbdfbcc7b 100644 --- a/docs/project/goals.md +++ b/docs/project/goals.md @@ -10,28 +10,28 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception -- [Overview](#overview) -- [Project goals](#project-goals) - - [Community and culture](#community-and-culture) - - [Language tools and ecosystem](#language-tools-and-ecosystem) -- [Language goals and priorities](#language-goals-and-priorities) - - [Goals in detail](#goals-in-detail) - - [Performance-critical software](#performance-critical-software) - - [Software and language evolution](#software-and-language-evolution) - - [Code that is easy to read, understand, and write](#code-that-is-easy-to-read-understand-and-write) - - [Practical safety guarantees and testing mechanisms](#practical-safety-guarantees-and-testing-mechanisms) - - [Fast and scalable development](#fast-and-scalable-development) - - [Modern OS platforms, hardware architectures, and environments](#modern-os-platforms-hardware-architectures-and-environments) - - [Interoperability with and migration from existing C++ code](#interoperability-with-and-migration-from-existing-c-code) - - [Non-goals](#non-goals) - - [Stable language and library ABI](#stable-language-and-library-abi) - - [Backwards or forwards compatibility](#backwards-or-forwards-compatibility) - - [Legacy compiled libraries without source code or ability to rebuild](#legacy-compiled-libraries-without-source-code-or-ability-to-rebuild) - - [Support for existing compilation and linking models](#support-for-existing-compilation-and-linking-models) - - [Idiomatic migration of non-modern, non-idiomatic C++ code](#idiomatic-migration-of-non-modern-non-idiomatic-c-code) - - [Principles](#principles) -- [Prioritization beyond goals](#prioritization-beyond-goals) -- [Acknowledgements](#acknowledgements) +- [Overview](#overview) +- [Project goals](#project-goals) + - [Community and culture](#community-and-culture) + - [Language tools and ecosystem](#language-tools-and-ecosystem) +- [Language goals and priorities](#language-goals-and-priorities) + - [Goals in detail](#goals-in-detail) + - [Performance-critical software](#performance-critical-software) + - [Software and language evolution](#software-and-language-evolution) + - [Code that is easy to read, understand, and write](#code-that-is-easy-to-read-understand-and-write) + - [Practical safety guarantees and testing mechanisms](#practical-safety-guarantees-and-testing-mechanisms) + - [Fast and scalable development](#fast-and-scalable-development) + - [Modern OS platforms, hardware architectures, and environments](#modern-os-platforms-hardware-architectures-and-environments) + - [Interoperability with and migration from existing C++ code](#interoperability-with-and-migration-from-existing-c-code) + - [Non-goals](#non-goals) + - [Stable language and library ABI](#stable-language-and-library-abi) + - [Backwards or forwards compatibility](#backwards-or-forwards-compatibility) + - [Legacy compiled libraries without source code or ability to rebuild](#legacy-compiled-libraries-without-source-code-or-ability-to-rebuild) + - [Support for existing compilation and linking models](#support-for-existing-compilation-and-linking-models) + - [Idiomatic migration of non-modern, non-idiomatic C++ code](#idiomatic-migration-of-non-modern-non-idiomatic-c-code) + - [Principles](#principles) +- [Prioritization beyond goals](#prioritization-beyond-goals) +- [Acknowledgements](#acknowledgements) @@ -296,22 +296,22 @@ activities where humans interact with Carbon: reading, writing, designing, discussing, reviewing, and refactoring code, as well as learning and teaching Carbon. A few examples: -- Carbon should not use symbols that are difficult to type, see, or - differentiate from similar symbols in commonly used contexts. -- Syntax should be easily parsed and scanned by any human in any development - environment, not just a machine or a human aided by semantic hints from an - IDE. -- Code with similar behavior should use similar syntax, and code with different - behavior should use different syntax. Behavior in this context should include - both the functionality and performance of the code. This is part of conceptual - integrity. -- Explicitness must be balanced against conciseness, as verbosity and ceremony - add cognitive overhead for the reader, while explicitness reduces the amount - of outside context the reader must have or assume. -- Common yet complex tasks, such as parallel code, should be well-supported in - ways that are easy to reason about. -- Ordinary tasks should not require extraordinary care, because humans cannot - consistently avoid making mistakes for an extended amount of time. +- Carbon should not use symbols that are difficult to type, see, or + differentiate from similar symbols in commonly used contexts. +- Syntax should be easily parsed and scanned by any human in any development + environment, not just a machine or a human aided by semantic hints from an + IDE. +- Code with similar behavior should use similar syntax, and code with + different behavior should use different syntax. Behavior in this context + should include both the functionality and performance of the code. This is + part of conceptual integrity. +- Explicitness must be balanced against conciseness, as verbosity and ceremony + add cognitive overhead for the reader, while explicitness reduces the amount + of outside context the reader must have or assume. +- Common yet complex tasks, such as parallel code, should be well-supported in + ways that are easy to reason about. +- Ordinary tasks should not require extraordinary care, because humans cannot + consistently avoid making mistakes for an extended amount of time. **Support tooling at every layer of the development experience, including IDEs.** The design and implementation of Carbon should make it easy to create diff --git a/docs/project/groups.md b/docs/project/groups.md index 45e7b7fa3ec0..1a2179cd8f05 100644 --- a/docs/project/groups.md +++ b/docs/project/groups.md @@ -11,24 +11,24 @@ tracking. We use a mix of: -- Groups to assist contacting key contributors on appropriate systems: - - **GitHub teams** - - **Discourse Forums groups** - - **Discord Chat roles** -- **Google groups**, usually as Google Drive ACLs. We generally won't use these - as contact lists, unless specifically mentioned. Please prefer Discourse - Forums. +- Groups to assist contacting key contributors on appropriate systems: + - **GitHub teams** + - **Discourse Forums groups** + - **Discord Chat roles** +- **Google groups**, usually as Google Drive ACLs. We generally won't use + these as contact lists, unless specifically mentioned. Please prefer + Discourse Forums. ## All contributors -- [GitHub organization](https://github.com/orgs/carbon-language/people) - - [GitHub team: Contributors with label access](https://github.com/orgs/carbon-language/teams/contributors-with-label-access): - Mirrors the GitHub organization for write access. - [Manually updated](/src/scripts/update-label-access.js). -- [Discourse Forums account](https://forums.carbon-lang.dev) -- [Discord Chat access](https://discord.com/app) -- [Google group](https://groups.google.com/g/carbon-lang-contributors): Grants - Google Drive access. +- [GitHub organization](https://github.com/orgs/carbon-language/people) + - [GitHub team: Contributors with label access](https://github.com/orgs/carbon-language/teams/contributors-with-label-access): + Mirrors the GitHub organization for write access. + [Manually updated](/src/scripts/update-label-access.js). +- [Discourse Forums account](https://forums.carbon-lang.dev) +- [Discord Chat access](https://discord.com/app) +- [Google group](https://groups.google.com/g/carbon-lang-contributors): Grants + Google Drive access. ## Team-specific access @@ -37,27 +37,27 @@ when somebody joins the respective team. ### Admins -- [GitHub owners](https://github.com/orgs/carbon-language/people?query=role%3Aowner) -- [Discourse Forums group](https://forums.carbon-lang.dev/g/admins) -- Discord Chat role: admin +- [GitHub owners](https://github.com/orgs/carbon-language/people?query=role%3Aowner) +- [Discourse Forums group](https://forums.carbon-lang.dev/g/admins) +- Discord Chat role: admin ### Conduct team For most purposes, the Core team should be contacted about conduct issues. -- [Google group](https://groups.google.com/g/carbon-lang-conduct-team): - Primarily a contact list. +- [Google group](https://groups.google.com/g/carbon-lang-conduct-team): + Primarily a contact list. ### Core team -- [GitHub team](https://github.com/orgs/carbon-language/teams/core-team) -- [Discourse Forums group](https://forums.carbon-lang.dev/g/core_team) -- Discord Chat role: core-team +- [GitHub team](https://github.com/orgs/carbon-language/teams/core-team) +- [Discourse Forums group](https://forums.carbon-lang.dev/g/core_team) +- Discord Chat role: core-team ### Review managers -- [GitHub team](https://github.com/orgs/carbon-language/teams/review-managers) -- [Discourse Forums group](https://forums.carbon-lang.dev/g/review_managers) -- Discord Chat role: review-managers -- [Google group](https://groups.google.com/g/carbon-lang-review-managers): - Grants Google Drive access. +- [GitHub team](https://github.com/orgs/carbon-language/teams/review-managers) +- [Discourse Forums group](https://forums.carbon-lang.dev/g/review_managers) +- Discord Chat role: review-managers +- [Google group](https://groups.google.com/g/carbon-lang-review-managers): + Grants Google Drive access. diff --git a/docs/project/principles/success_criteria.md b/docs/project/principles/success_criteria.md index ede7963dd76f..45b748d84ce0 100644 --- a/docs/project/principles/success_criteria.md +++ b/docs/project/principles/success_criteria.md @@ -10,14 +10,14 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception -- [Principle](#principle) -- [Applications of these principles](#applications-of-these-principles) - - [Modern OS platforms, hardware architectures, and environments](#modern-os-platforms-hardware-architectures-and-environments) - - [OS platforms](#os-platforms) - - [Hardware architectures](#hardware-architectures) - - [Historical platforms](#historical-platforms) - - [Interoperability with and migration from existing C++ code](#interoperability-with-and-migration-from-existing-c-code) - - [Migration tooling](#migration-tooling) +- [Principle](#principle) +- [Applications of these principles](#applications-of-these-principles) + - [Modern OS platforms, hardware architectures, and environments](#modern-os-platforms-hardware-architectures-and-environments) + - [OS platforms](#os-platforms) + - [Hardware architectures](#hardware-architectures) + - [Historical platforms](#historical-platforms) + - [Interoperability with and migration from existing C++ code](#interoperability-with-and-migration-from-existing-c-code) + - [Migration tooling](#migration-tooling) @@ -49,22 +49,22 @@ This should not be considered an exhaustive list of important platforms. Our priority OS platforms are modern versions of: -- Linux, including common distributions, Android and ChromeOS -- FreeBSD -- Windows -- macOS and iOS -- Fuchsia -- WebAssembly -- Bare metal +- Linux, including common distributions, Android and ChromeOS +- FreeBSD +- Windows +- macOS and iOS +- Fuchsia +- WebAssembly +- Bare metal #### Hardware architectures We expect to prioritize 64-bit little endian hardware, including: -- x86-64 -- AArch64, also known as ARM 64-bit -- PPC64LE, also known as Power ISA, 64-bit, Little Endian -- RV64I, also known as RISC-V 64-bit +- x86-64 +- AArch64, also known as ARM 64-bit +- PPC64LE, also known as Power ISA, 64-bit, Little Endian +- RV64I, also known as RISC-V 64-bit We believe Carbon should strive to support some GPUs, other restricted computational hardware and environments, and embedded environments. While this @@ -76,15 +76,15 @@ while they remain relatively new and rapidly evolving. Example historical platforms that we will not prioritize support for are: -- Byte sizes other than 8 bits, or non-power-of-two word sizes. -- Source code encodings other than UTF-8. -- Big- or mixed-endian, at least for computation; accessing encoded data remains - useful. -- Non-2's-complement integer formats. -- Non-IEEE 754 binary floating point format and semantics for default single- - and double-precision floating point types. -- Source code in file systems that don’t support file extensions or nested - directories. +- Byte sizes other than 8 bits, or non-power-of-two word sizes. +- Source code encodings other than UTF-8. +- Big- or mixed-endian, at least for computation; accessing encoded data + remains useful. +- Non-2's-complement integer formats. +- Non-IEEE 754 binary floating point format and semantics for default single- + and double-precision floating point types. +- Source code in file systems that don’t support file extensions or nested + directories. ### Interoperability with and migration from existing C++ code @@ -99,11 +99,12 @@ human interaction. This criterion includes: -- Addressing performance bugs unique to Carbon, introduced by migration tooling. -- Converting complex code which migration tooling does not handle. +- Addressing performance bugs unique to Carbon, introduced by migration + tooling. +- Converting complex code which migration tooling does not handle. This criterion does not include: -- Cleaning up coding style to idiomatic Carbon. - - For example, heavy use of C++ preprocessor macros may result in expanded - code where there is no equivalent Carbon metaprogramming construct. +- Cleaning up coding style to idiomatic Carbon. + - For example, heavy use of C++ preprocessor macros may result in expanded + code where there is no equivalent Carbon metaprogramming construct. diff --git a/docs/project/pull_request_workflow.md b/docs/project/pull_request_workflow.md index a87f0ee79dd8..e882abef5ca5 100644 --- a/docs/project/pull_request_workflow.md +++ b/docs/project/pull_request_workflow.md @@ -8,26 +8,27 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception Carbon repositories follow a few basic principles: -- Development directly on the `trunk` branch and - [revert to green](#green-tests). -- Always use pull requests, rather than pushing directly. -- Changes should be small, incremental, and review-optimized. -- Preserve linear history by - [rebasing](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-merges#rebase-and-merge-your-pull-request-commits) - or - [squashing](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-merges#squash-and-merge-your-pull-request-commits) - pull requests rather than using unsquashed merge commits. +- Development directly on the `trunk` branch and + [revert to green](#green-tests). +- Always use pull requests, rather than pushing directly. +- Changes should be small, incremental, and review-optimized. +- Preserve linear history by + [rebasing](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-merges#rebase-and-merge-your-pull-request-commits) + or + [squashing](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-merges#squash-and-merge-your-pull-request-commits) + pull requests rather than using unsquashed merge commits. These principles try to optimize for several different uses or activities with version control: -- Continuous integration and bisection to identify failures and revert to green. -- Code review both at the time of commit and follow-up review after commit. -- Understanding how things evolve over time, which can manifest in different - ways: - - When were things introduced? - - How does the main branch and project evolve over time? - - How was a bug or surprising thing introduced? +- Continuous integration and bisection to identify failures and revert to + green. +- Code review both at the time of commit and follow-up review after commit. +- Understanding how things evolve over time, which can manifest in different + ways: + - When were things introduced? + - How does the main branch and project evolve over time? + - How was a bug or surprising thing introduced? Note that this isn't a complete guide to doing code reviews, and just focuses on the mechanical workflow and branch management. TODO: Add an explicit link to diff --git a/docs/project/review_managers.md b/docs/project/review_managers.md index 360d2ce2fe5f..234a1efceae0 100644 --- a/docs/project/review_managers.md +++ b/docs/project/review_managers.md @@ -11,12 +11,12 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception As part of [assisting in the evolution process](evolution.md#review-managers), review managers are expected to: -- Monitor and respond to topics in - [Evolution > Review manager requests](https://forums.carbon-lang.dev/c/evolution/review-manager-requests/15). -- Announce when RFCs are approaching - [readiness for a decision](evolution.md#request-a-review-manager). -- [Escort the proposal to a decision.](evolution.md#ask-the-reviewing-team-for-a-proposal-decision) -- [Author and publish proposal decisions.](evolution.md#finalize-the-proposal-decision) +- Monitor and respond to topics in + [Evolution > Review manager requests](https://forums.carbon-lang.dev/c/evolution/review-manager-requests/15). +- Announce when RFCs are approaching + [readiness for a decision](evolution.md#request-a-review-manager). +- [Escort the proposal to a decision.](evolution.md#ask-the-reviewing-team-for-a-proposal-decision) +- [Author and publish proposal decisions.](evolution.md#finalize-the-proposal-decision) Review managers should additionally provide advice and assistance to proposal authors where appropriate, to help ensure the smooth operation of the evolution @@ -55,8 +55,8 @@ titled "Request for decision: PROPOSAL": Links: -- [Proposal PR](LINK) -- [RFC topic](LINK) +- [Proposal PR](LINK) +- [RFC topic](LINK) Please focus on affirm, object, and stand aside comments in this topic; other things specific to reaching consensus may be included. Affirm and object @@ -95,9 +95,9 @@ titled "[DECISION] PROPOSAL": Please read the [formal decision PR](LINK) for details. -- [Proposal PR](LINK) -- [RFC topic](LINK) -- [Decision topic](link) +- [Proposal PR](LINK) +- [RFC topic](LINK) +- [Decision topic](link) This decision is now entering the [decision comment period](https://carbon-lang.dev/docs/project/evolution.html#community-comments-on-proposal-decision), diff --git a/proposals/README.md b/proposals/README.md index 7cf8e3150326..3d0ec2da4549 100644 --- a/proposals/README.md +++ b/proposals/README.md @@ -13,22 +13,22 @@ original pull request. For accepted proposals, where `####` is the corresponding proposal's pull request: -- `p####.md` will contain the main proposal text. -- `p####-decision.md` documents the decision and rationale. -- `p####` may be present as an optional subdirectory for related files (e.g., - images). +- `p####.md` will contain the main proposal text. +- `p####-decision.md` documents the decision and rationale. +- `p####` may be present as an optional subdirectory for related files (e.g., + images). ## Proposal list -- [0029 - Linear, rebase, and pull-request GitHub workflow](p0029.md) - - [Decision](p0029-decision.md) -- [0044 - Proposal tracking](p0044.md) - - [Decision](p0044-decision.md) -- [0051 - Goals](p0051.md) -- [0074 - Change comment/decision timelines in proposal process](p0074.md) - - [Decision](p0074-decision.md) +- [0029 - Linear, rebase, and pull-request GitHub workflow](p0029.md) + - [Decision](p0029-decision.md) +- [0044 - Proposal tracking](p0044.md) + - [Decision](p0044-decision.md) +- [0051 - Goals](p0051.md) +- [0074 - Change comment/decision timelines in proposal process](p0074.md) + - [Decision](p0074-decision.md) diff --git a/proposals/p0029-decision.md b/proposals/p0029-decision.md index 9e7104ab23ac..d15fb8d1ddeb 100644 --- a/proposals/p0029-decision.md +++ b/proposals/p0029-decision.md @@ -10,23 +10,23 @@ Proposal accepted on 2020-06-30 Affirming: -- [austern](https://github.com/austern) -- [chandlerc](https://github.com/chandlerc) -- [geoffromer](https://github.com/geoffromer) -- [josh11b](https://github.com/josh11b) -- [zygoloid](https://github.com/zygoloid) +- [austern](https://github.com/austern) +- [chandlerc](https://github.com/chandlerc) +- [geoffromer](https://github.com/geoffromer) +- [josh11b](https://github.com/josh11b) +- [zygoloid](https://github.com/zygoloid) Abstaining: -- [gribozavr](https://github.com/gribozavr) -- [noncombatant](https://github.com/noncombatant) -- [tituswinters](https://github.com/tituswinters) +- [gribozavr](https://github.com/gribozavr) +- [noncombatant](https://github.com/noncombatant) +- [tituswinters](https://github.com/tituswinters) ## Rationale -- Easy to follow single source of truth will help foster an open and inclusive - community. -- Review requirements and focus on small, incremental changes match well - established engineering practices for ensuring the project and codebase scale - up both in size and time dimensions. -- Linear history seems easier for humans to reason about. +- Easy to follow single source of truth will help foster an open and inclusive + community. +- Review requirements and focus on small, incremental changes match well + established engineering practices for ensuring the project and codebase + scale up both in size and time dimensions. +- Linear history seems easier for humans to reason about. diff --git a/proposals/p0029.md b/proposals/p0029.md index a3809a28b0f1..c6579cb374ad 100644 --- a/proposals/p0029.md +++ b/proposals/p0029.md @@ -18,13 +18,13 @@ and can be handled on a case-by-case basis when they arise. ## Background -- Chapter 16 "Version Control and Branch Management" in the SWE book - (_[Software Engineering at Google](https://www.amazon.com/Software-Engineering-Google-Lessons-Programming/dp/1492082791)_) -- [Trunk Based Development](https://trunkbaseddevelopment.com/) -- GitHub documentation on - "[pull requests](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests)" - - [Configuration of their merges](https://help.github.com/en/github/administering-a-repository/configuring-pull-request-merges) - - [Protected branches](https://help.github.com/en/github/administering-a-repository/about-protected-branches) +- Chapter 16 "Version Control and Branch Management" in the SWE book + (_[Software Engineering at Google](https://www.amazon.com/Software-Engineering-Google-Lessons-Programming/dp/1492082791)_) +- [Trunk Based Development](https://trunkbaseddevelopment.com/) +- GitHub documentation on + "[pull requests](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests)" + - [Configuration of their merges](https://help.github.com/en/github/administering-a-repository/configuring-pull-request-merges) + - [Protected branches](https://help.github.com/en/github/administering-a-repository/about-protected-branches) ## Proposal @@ -91,22 +91,22 @@ are allowed for rare events like contributing a new subproject. Pros: -- Still has linear history. -- Incentivizes squashing for continuous integration and bisection. -- Very low overhead for fixing trivial mistakes. +- Still has linear history. +- Incentivizes squashing for continuous integration and bisection. +- Very low overhead for fixing trivial mistakes. Cons: -- Creates extremely bad incentives around code review. - - Lots of patches don't get pre-commit review, even if they would benefit from - it. - - Very experienced contributors are much better at avoiding pre-commit review, - so are rarely blocked waiting on review. - - Leads to the most experienced members of the community not doing enough code - reviews, or being timely enough in code reviews. - - Lots of patches submitted with post-commit review are never reviewed in - practice unless they break something. -- UI and basic support for code reviews entirely focused on pull requests. +- Creates extremely bad incentives around code review. + - Lots of patches don't get pre-commit review, even if they would benefit + from it. + - Very experienced contributors are much better at avoiding pre-commit + review, so are rarely blocked waiting on review. + - Leads to the most experienced members of the community not doing enough + code reviews, or being timely enough in code reviews. + - Lots of patches submitted with post-commit review are never reviewed in + practice unless they break something. +- UI and basic support for code reviews entirely focused on pull requests. ### Fork and merge model @@ -115,26 +115,29 @@ development. Pros: -- Mostly supported by pull requests, so still able to use much of that - functionality. -- Supports a model in which contributors do not communicate and can each develop - a local, decentralized fork while still achieving overall reconciliation. -- Can model much more complex history of code evolution faithfully in the - tooling. - - Most of the time these aren't so complex that they create problems for - humans. +- Mostly supported by pull requests, so still able to use much of that + functionality. +- Supports a model in which contributors do not communicate and can each + develop a local, decentralized fork while still achieving overall + reconciliation. +- Can model much more complex history of code evolution faithfully in the + tooling. + - Most of the time these aren't so complex that they create problems for + humans. Cons: -- History is harder for humans to understand and reason about in complex cases. -- Bisection and continuous integration are more complex. - - May create difficulty for continuous integration against mainline, because - unclear what "order" they should be applied / explored. While there are - technical approaches to address this, the don't seem to eliminate the - complexity, merely provide a clear set of mechanics for handling it. -- Reduces incentives to land small, incremental changes by allowing - non-linearity to reduce the effort required for large and/or complex merges. -- Makes review of the main branch's history harder due to non-linearity. +- History is harder for humans to understand and reason about in complex + cases. +- Bisection and continuous integration are more complex. + - May create difficulty for continuous integration against mainline, + because unclear what "order" they should be applied / explored. While + there are technical approaches to address this, the don't seem to + eliminate the complexity, merely provide a clear set of mechanics for + handling it. +- Reduces incentives to land small, incremental changes by allowing + non-linearity to reduce the effort required for large and/or complex merges. +- Makes review of the main branch's history harder due to non-linearity. ### Fork and merge, but branches can only have linear history @@ -145,13 +148,14 @@ themselves don’t contain merge commits. Pros: -- Mostly supported by GitHub pull requests, so still able to use much of that - functionality. -- Restricts non-linearity of history. The only non-linearity that is left is - merge commits on the trunk branch. PRs themselves can’t contain merge commits. +- Mostly supported by GitHub pull requests, so still able to use much of that + functionality. +- Restricts non-linearity of history. The only non-linearity that is left is + merge commits on the trunk branch. PRs themselves can’t contain merge + commits. Cons: -- Requires a custom presubmit on GitHub that checks linearity of a PR. -- The cons of the fork and merge strategy regarding the complexity of history - remain, but to a smaller degree, since non-linearity is restricted. +- Requires a custom presubmit on GitHub that checks linearity of a PR. +- The cons of the fork and merge strategy regarding the complexity of history + remain, but to a smaller degree, since non-linearity is restricted. diff --git a/proposals/p0044-decision.md b/proposals/p0044-decision.md index 09035824b728..c0d8205cd831 100644 --- a/proposals/p0044-decision.md +++ b/proposals/p0044-decision.md @@ -10,17 +10,17 @@ Proposal accepted on 2020-06-02 Affirming: -- [austern](https://github.com/austern) -- [chandlerc](https://github.com/chandlerc) -- [geoffromer](https://github.com/geoffromer) -- [gribozavr](https://github.com/gribozavr) -- [josh11b](https://github.com/josh11b) -- [zygoloid](https://github.com/zygoloid) +- [austern](https://github.com/austern) +- [chandlerc](https://github.com/chandlerc) +- [geoffromer](https://github.com/geoffromer) +- [gribozavr](https://github.com/gribozavr) +- [josh11b](https://github.com/josh11b) +- [zygoloid](https://github.com/zygoloid) Abstaining: -- [noncombatant](https://github.com/noncombatant) -- [tituswinters](https://github.com/tituswinters) +- [noncombatant](https://github.com/noncombatant) +- [tituswinters](https://github.com/tituswinters) ## Open questions @@ -65,22 +65,22 @@ etc. In general, the PR-centric model was favored. ### Rationale for using a GitHub markdown-centric flow -- The GitHub markdown-centric flow makes the on-ramp as smooth as possible for - external contributors. - - This positions the project to maximize the ease of engaging with and gaining - contributions from the wider industry. -- The final documents must be in markdown form, so it is best if contributors - have the option to stay in markdown for the whole process. This is - significantly less complex than something that converts between formats: +- The GitHub markdown-centric flow makes the on-ramp as smooth as possible for + external contributors. + - This positions the project to maximize the ease of engaging with and + gaining contributions from the wider industry. +- The final documents must be in markdown form, so it is best if contributors + have the option to stay in markdown for the whole process. This is + significantly less complex than something that converts between formats: - - Less to learn - - Fewer steps in the process - - No outdated versions in the old format left behind + - Less to learn + - Fewer steps in the process + - No outdated versions in the old format left behind -- The technical flow seems on balance better than the Google Docs-based - workflow. The proposal does a really good job explaining pros and cons. In - summary, the Google Docs-centric workflow has a lot of cons that make it - difficult to work with proposals over the long term. +- The technical flow seems on balance better than the Google Docs-based + workflow. The proposal does a really good job explaining pros and cons. In + summary, the Google Docs-centric workflow has a lot of cons that make it + difficult to work with proposals over the long term. ### Rationale for not requiring tracking issues @@ -90,35 +90,35 @@ issues, the process is more light-weight without them. ### Rationale for not committing proposals that are declined or deferred -- This approach seems simpler. -- When a proposal PR includes the changes put forth in the proposal (PR-centric - model), the declined PR might need to be considerably changed--and might lose - context--in order to be committed. -- The community will put a lot of work into developing, discussing, and making a - decision on a proposal. There may be valuable insight in rejected proposals, - so it makes sense to archive them. However, as noted, committing the PR will - not always be possible with reasonable effort if not working in a - proposal-centric model, as the proposal text may not stand on its own. -- While we may discover issues with this approach, it is better to try this way, - see if any issues can be rectified, and propose changes as necessary. +- This approach seems simpler. +- When a proposal PR includes the changes put forth in the proposal + (PR-centric model), the declined PR might need to be considerably + changed--and might lose context--in order to be committed. +- The community will put a lot of work into developing, discussing, and making + a decision on a proposal. There may be valuable insight in rejected + proposals, so it makes sense to archive them. However, as noted, committing + the PR will not always be possible with reasonable effort if not working in + a proposal-centric model, as the proposal text may not stand on its own. +- While we may discover issues with this approach, it is better to try this + way, see if any issues can be rectified, and propose changes as necessary. ### Rationale for committing a proposal to the repository it affects -- This keeps the proposal close to the repository, and therefore, the community, - that it affects. -- It facilitates autonomy of (future) review teams responsible for a particular - aspect of Carbon. For example, a reference implementation team responsible for - the carbon-toolchain repository. -- It simplifies the common case and makes it easier to find how each repository - evolves over time. +- This keeps the proposal close to the repository, and therefore, the + community, that it affects. +- It facilitates autonomy of (future) review teams responsible for a + particular aspect of Carbon. For example, a reference implementation team + responsible for the carbon-toolchain repository. +- It simplifies the common case and makes it easier to find how each + repository evolves over time. ### Rationale for pushing high-level comments to GitHub While opinions were not as strong, reasons given for perferring comments in GitHub: -- This flow will maximize the alignment with “normal” GitHub development flow. - - This both improves pulling external/new people into the flow, and will - reduce the number of flows they need to learn/remember/tool for. -- We will get ecosystem benefits as this flow continues to be optimized by - GitHub and those using it. +- This flow will maximize the alignment with “normal” GitHub development flow. + - This both improves pulling external/new people into the flow, and will + reduce the number of flows they need to learn/remember/tool for. +- We will get ecosystem benefits as this flow continues to be optimized by + GitHub and those using it. diff --git a/proposals/p0044.md b/proposals/p0044.md index 3054f95a7dba..ef62ea124193 100644 --- a/proposals/p0044.md +++ b/proposals/p0044.md @@ -12,57 +12,57 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception -- [Problem](#problem) -- [Background](#background) -- [Proposal](#proposal) - - [Overview](#overview) - - [Open question: Do we use a Google Docs-centric or GitHub Markdown-centric flow?](#open-question-do-we-use-a-google-docs-centric-or-github-markdown-centric-flow) - - [Option: Google Docs-centric flow](#option-google-docs-centric-flow) - - [Overview](#overview-1) - - [Flow summary](#flow-summary) - - [Pros/Cons](#proscons) - - [Option: GitHub Markdown-centric flow](#option-github-markdown-centric-flow) - - [Overview](#overview-2) - - [Flow summary](#flow-summary-1) - - [Pros/Cons](#proscons-1) -- [Details](#details) - - [Carbon language shared drive](#carbon-language-shared-drive) - - [Main shared drive](#main-shared-drive) - - [Proposals (shared folder)](#proposals-shared-folder) - - [Proposal Archive (folder in shared drive)](#proposal-archive-folder-in-shared-drive) - - [Google Docs proposal ACLs](#google-docs-proposal-acls) -- [Markdown-specific questions](#markdown-specific-questions) - - [Open question: Where should proposals be stored in GitHub?](#open-question-where-should-proposals-be-stored-in-github) - - [Option: Proposal archive GitHub repo (carbon-proposals)](#option-proposal-archive-github-repo-carbon-proposals) - - [Option: Store proposals in the repository they affect](#option-store-proposals-in-the-repository-they-affect) - - [Open question: Should we push comments to focus on GitHub?](#open-question-should-we-push-comments-to-focus-on-github) - - [Common principles](#common-principles) - - [Option: Push high-level comments to Discourse Forums](#option-push-high-level-comments-to-discourse-forums) - - [Option: Push high-level comments to GitHub](#option-push-high-level-comments-to-github) - - [Option: Give no guidance, see what happens](#option-give-no-guidance-see-what-happens) - - [Open question: Should there be a tracking issue?](#open-question-should-there-be-a-tracking-issue) - - [Common principles](#common-principles-1) - - [Option: Tracking issue for all proposals](#option-tracking-issue-for-all-proposals) - - [Option: Don't require tracking issues](#option-dont-require-tracking-issues) - - [Open question: Should declined/deferred proposals be committed?](#open-question-should-declineddeferred-proposals-be-committed) - - [Common principles](#common-principles-2) - - [Option: Do not commit declined/deferred proposals](#option-do-not-commit-declineddeferred-proposals) - - [Option: Commit declined/deferred proposals](#option-commit-declineddeferred-proposals) -- [Alternatives considered](#alternatives-considered) - - [Use a shared drive for everything](#use-a-shared-drive-for-everything) -- [Appendix](#appendix) - - [General concern about multiple Markdown flavors](#general-concern-about-multiple-markdown-flavors) - - [Google Docs vs GitHub comment flow comparison](#google-docs-vs-github-comment-flow-comparison) - - [Comment clustering](#comment-clustering) - - [Basic comments](#basic-comments) - - [Suggesting edits](#suggesting-edits) - - [Google Docs add-ons](#google-docs-add-ons) - - [Docs to Markdown](#docs-to-markdown) - - [Code blocks](#code-blocks) - - [Advanced Find & Replace](#advanced-find--replace) - - [Markdown editing](#markdown-editing) - - [StackEdit](#stackedit) - - [GitHub Markdown syntax highlighting](#github-markdown-syntax-highlighting) +- [Problem](#problem) +- [Background](#background) +- [Proposal](#proposal) + - [Overview](#overview) + - [Open question: Do we use a Google Docs-centric or GitHub Markdown-centric flow?](#open-question-do-we-use-a-google-docs-centric-or-github-markdown-centric-flow) + - [Option: Google Docs-centric flow](#option-google-docs-centric-flow) + - [Overview](#overview-1) + - [Flow summary](#flow-summary) + - [Pros/Cons](#proscons) + - [Option: GitHub Markdown-centric flow](#option-github-markdown-centric-flow) + - [Overview](#overview-2) + - [Flow summary](#flow-summary-1) + - [Pros/Cons](#proscons-1) +- [Details](#details) + - [Carbon language shared drive](#carbon-language-shared-drive) + - [Main shared drive](#main-shared-drive) + - [Proposals (shared folder)](#proposals-shared-folder) + - [Proposal Archive (folder in shared drive)](#proposal-archive-folder-in-shared-drive) + - [Google Docs proposal ACLs](#google-docs-proposal-acls) +- [Markdown-specific questions](#markdown-specific-questions) + - [Open question: Where should proposals be stored in GitHub?](#open-question-where-should-proposals-be-stored-in-github) + - [Option: Proposal archive GitHub repo (carbon-proposals)](#option-proposal-archive-github-repo-carbon-proposals) + - [Option: Store proposals in the repository they affect](#option-store-proposals-in-the-repository-they-affect) + - [Open question: Should we push comments to focus on GitHub?](#open-question-should-we-push-comments-to-focus-on-github) + - [Common principles](#common-principles) + - [Option: Push high-level comments to Discourse Forums](#option-push-high-level-comments-to-discourse-forums) + - [Option: Push high-level comments to GitHub](#option-push-high-level-comments-to-github) + - [Option: Give no guidance, see what happens](#option-give-no-guidance-see-what-happens) + - [Open question: Should there be a tracking issue?](#open-question-should-there-be-a-tracking-issue) + - [Common principles](#common-principles-1) + - [Option: Tracking issue for all proposals](#option-tracking-issue-for-all-proposals) + - [Option: Don't require tracking issues](#option-dont-require-tracking-issues) + - [Open question: Should declined/deferred proposals be committed?](#open-question-should-declineddeferred-proposals-be-committed) + - [Common principles](#common-principles-2) + - [Option: Do not commit declined/deferred proposals](#option-do-not-commit-declineddeferred-proposals) + - [Option: Commit declined/deferred proposals](#option-commit-declineddeferred-proposals) +- [Alternatives considered](#alternatives-considered) + - [Use a shared drive for everything](#use-a-shared-drive-for-everything) +- [Appendix](#appendix) + - [General concern about multiple Markdown flavors](#general-concern-about-multiple-markdown-flavors) + - [Google Docs vs GitHub comment flow comparison](#google-docs-vs-github-comment-flow-comparison) + - [Comment clustering](#comment-clustering) + - [Basic comments](#basic-comments) + - [Suggesting edits](#suggesting-edits) + - [Google Docs add-ons](#google-docs-add-ons) + - [Docs to Markdown](#docs-to-markdown) + - [Code blocks](#code-blocks) + - [Advanced Find & Replace](#advanced-find--replace) + - [Markdown editing](#markdown-editing) + - [StackEdit](#stackedit) + - [GitHub Markdown syntax highlighting](#github-markdown-syntax-highlighting) @@ -70,9 +70,9 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception How should we: -- Draft proposals? -- Store under review proposals? -- Archive proposals? +- Draft proposals? +- Store under review proposals? +- Archive proposals? Each of these is a distinct, important step. We may be able to use the same storage for multiple steps. @@ -86,13 +86,13 @@ proposal goes to Markdown. The evolution process expects that community contributors will author proposals for review by the core team. Things to consider are: -- How easy is it for an author to write a proposal? - - What if there are multiple contributors to a proposal? -- How easy is it to comment on a proposal? - - What about small typo fixes? -- How do we prevent unwanted edits during the comment process? -- How much work does it take to convert a proposal into a final doc edit? -- How do we prevent edits after a decision is complete? +- How easy is it for an author to write a proposal? + - What if there are multiple contributors to a proposal? +- How easy is it to comment on a proposal? + - What about small typo fixes? +- How do we prevent unwanted edits during the comment process? +- How much work does it take to convert a proposal into a final doc edit? +- How do we prevent edits after a decision is complete? In any situation, it's necessary that proposals be clearly contributed to Carbon (even if in a draft phase, even if never accepted), and have an appropriate @@ -129,234 +129,242 @@ possible flows: ##### Overview -- Draft proposals: Google Docs -- Under review proposals: Google Docs -- Archive proposals: Google Docs + PDF -- Final format: Markdown +- Draft proposals: Google Docs +- Under review proposals: Google Docs +- Archive proposals: Google Docs + PDF +- Final format: Markdown ##### Flow summary For reviewing a proposal: -- Authors create a Google Doc in the Proposals shared folder. - - Authors may want to trim down edit access, leaving only comment access. -- When ready for review, the authors share the Google Doc on Discourse Forums. - - Community comments on the Google Doc. -- To move for a decision, ownership is transferred to a review manager. - - The review manager trims down all access to comment access. -- When a decision is reached, the review manager updates the doc and moves it to - the Proposal Archive folder in the Carbon language shared drive. -- A PDF is saved to the carbon-proposals GitHub repo. -- The author converts any long-term documentation portions of the doc to - Markdown. +- Authors create a Google Doc in the Proposals shared folder. + - Authors may want to trim down edit access, leaving only comment access. +- When ready for review, the authors share the Google Doc on Discourse Forums. + - Community comments on the Google Doc. +- To move for a decision, ownership is transferred to a review manager. + - The review manager trims down all access to comment access. +- When a decision is reached, the review manager updates the doc and moves it + to the Proposal Archive folder in the Carbon language shared drive. +- A PDF is saved to the carbon-proposals GitHub repo. +- The author converts any long-term documentation portions of the doc to + Markdown. If the proposal needs to be checked later to figure out why a decision was made: -- Pragmatically, the PDF should have the same viewable content as the Google - Doc, and so can be used. -- The Google Doc's comments will be a mess to read, and so should likely be - treated as inaccessible later. -- The edit history of a Google Doc is only visible to users with edit access. - Since most people will have comment-only or view-only access to reviewed docs, - we should treat edit history as not accessible. +- Pragmatically, the PDF should have the same viewable content as the Google + Doc, and so can be used. +- The Google Doc's comments will be a mess to read, and so should likely be + treated as inaccessible later. +- The edit history of a Google Doc is only visible to users with edit access. + Since most people will have comment-only or view-only access to reviewed + docs, we should treat edit history as not accessible. ##### Pros/Cons Pros: -- Supports collaborative editing. -- Commenting in Docs is a slightly better UI, even though the commenting - workflows are equivalent. -- Images can easily be embedded in the Google Doc, without needing separate - files. +- Supports collaborative editing. +- Commenting in Docs is a slightly better UI, even though the commenting + workflows are equivalent. +- Images can easily be embedded in the Google Doc, without needing separate + files. Neutral: -- Has an easier [suggested edit workflow](#suggesting-edits) than GitHub. - - For commenters, this may be a pro because they can see their suggested edit - as they make it. - - For the author, this is a mixed bag: - - When a suggestion is for multiple, fragmented edits, it's harder to read. - - e.g., "foo ~~bar ~~baaz bang~~wiz ~~bing" -> "foo baaz bangbing" - - It's easier to accept changes. - - It's harder to comment on changes, as the change is still visible and - hiding the original state of the doc. - - This is especially true when trying to respond to comments by others on - a suggested edit, as you can't _both_ have a discussion _and_ - apply/reject the edit. - - It's harder to make alternative edits and/or reject changes, as it - effectively resolves the comment thread and hinders further discussion. - - For other readers, this is likely a con: it's harder to read the original - state of the doc that's been suggested on, and it's not clear how the author - will respond. +- Has an easier [suggested edit workflow](#suggesting-edits) than GitHub. + - For commenters, this may be a pro because they can see their suggested + edit as they make it. + - For the author, this is a mixed bag: + - When a suggestion is for multiple, fragmented edits, it's harder to + read. + - e.g., "foo ~~bar ~~baaz bang~~wiz ~~bing" -> "foo baaz bangbing" + - It's easier to accept changes. + - It's harder to comment on changes, as the change is still visible + and hiding the original state of the doc. + - This is especially true when trying to respond to comments by + others on a suggested edit, as you can't _both_ have a + discussion _and_ apply/reject the edit. + - It's harder to make alternative edits and/or reject changes, as it + effectively resolves the comment thread and hinders further + discussion. + - For other readers, this is likely a con: it's harder to read the + original state of the doc that's been suggested on, and it's not clear + how the author will respond. Cons: -- Documents will go through at least three different file formats (Docs, PDF, - Markdown). - - Docs->Markdown conversion has limited tooling support. - - Comment history will be lost on conversions. - - Using different formats for proposals and documentation/specification - creates additional work when pulling text into a proposal to suggest - modifications, and when applying those modifications. - - Any differences between the text in different formats will be difficult to - notice, particularly if the author makes a change when converting long-term - documentation from Docs to Markdown. -- Difficult to manage access control on files. - - Docs does not provide access to version history (desirable) without granting - full edit access (undesirable). - - Shared drives combine permissions for adding files to a folder and editing - files. Permissions can also only be _added_, not _removed_, from individual - docs. As a result, contributors who can create new proposals will also - receive the ability to edit all proposals. - - Docs will not automatically mirror permissions if we use two different - sharing systems (shared drive and shared folder). -- Difficult to archive documents as read-only. - - If we set archived documents to be view-only, users won't be able to read - comments. At that point, the PDF version that we plan to commit to the - Proposal archive GitHub repo is sufficient, and we could delete the - proposal. - - If we set archived documents to allow commenting, then users can comment on - and add suggested edits to archived documents. Only review managers could - close suggested edits. This could confuse the history of the doc, and stop - archives from looking read-only. - - In any case, archived documents would not be editable, and so revision - history could not be seen. -- Managing comments over time is infeasible. - - It's infeasible to point people to old comment threads, to suggest they read - and engage if they disagree with the original request. - - Even identifying _whether_ a comment led to a particular change is - infeasible. - - Comments vanish if the text they're on is removed. - - There is no way to quickly check for unresponded comments: instead, authors - will need to repeatedly crawl the doc. This is exacerbated by process advice - that the commenter be left to decide whether to resolve comments, or - slow-to-respond commenters. -- No support for seeing deltas. - - Only editors can see the delta. However, it should be expected that only the - author is an editor. - - Even if deltas were accessible, Docs delta support requires extra work on - the part of a doc editor to set up markers in the version history. -- Restricted support for extensibility. - - Proposals frequently have duplicated/boilerplate text that the authors may - need to rewrite in bulk, e.g. when renaming something. Google Docs has - built-in regex search. However, regex replace with capture groups isn't - directly supported, so users would need to learn and use Google Apps Script - to do the replacement. - - When URLs need to be replaced, Google Docs has _no_ support. Authors must - audit every URL. -- No low-friction support for formatted code blocks and inline code snippets. - - [Extensions exist](#google-docs-add-ons); we'll probably want to recommend a - specific extension to the community. -- Intra-document links break frequently, just from moving headers. - - It's also difficult to determine when an intra-document link is broken. - There doesn't seem to be support (built-in or add-on) for identifying - issues. - - It's also not supported to search through links, so even if the author knows - what they're breaking, they won't be able to find it. -- Google Docs comment syntax is essentially text-only. - - Syntax can interfere with "\*" insertion in code snippets due to bolding - confusion. -- May enhance Google-centric views of Carbon. - - Swift and Rust use Markdown-centric flows. -- Some companies may block Google Docs, because it's a file transfer service. - - It's unclear how prevalent this would be. GitHub may also be blocked under - similar security rules, but it's a requirement for participation whereas - Google Docs is avoidable. - - Ref: - [[1]](https://community.cisco.com/t5/web-security/blocking-google-docs/td-p/3376518), - [[2]](https://www.reddit.com/r/sysadmin/comments/2kwyhk/block_google_docs/), - [[3]](https://mybroadband.co.za/forum/threads/google-drive-blocked-at-work-work-around.809132/) -- Some individuals may refuse to use Google Docs over privacy (or other) - concerns. - - We've considered creating a GSuite domain for Carbon contributor accounts to - help address this. However, it may not address everyone's concerns. +- Documents will go through at least three different file formats (Docs, PDF, + Markdown). + - Docs->Markdown conversion has limited tooling support. + - Comment history will be lost on conversions. + - Using different formats for proposals and documentation/specification + creates additional work when pulling text into a proposal to suggest + modifications, and when applying those modifications. + - Any differences between the text in different formats will be difficult + to notice, particularly if the author makes a change when converting + long-term documentation from Docs to Markdown. +- Difficult to manage access control on files. + - Docs does not provide access to version history (desirable) without + granting full edit access (undesirable). + - Shared drives combine permissions for adding files to a folder and + editing files. Permissions can also only be _added_, not _removed_, from + individual docs. As a result, contributors who can create new proposals + will also receive the ability to edit all proposals. + - Docs will not automatically mirror permissions if we use two different + sharing systems (shared drive and shared folder). +- Difficult to archive documents as read-only. + - If we set archived documents to be view-only, users won't be able to + read comments. At that point, the PDF version that we plan to commit to + the Proposal archive GitHub repo is sufficient, and we could delete the + proposal. + - If we set archived documents to allow commenting, then users can comment + on and add suggested edits to archived documents. Only review managers + could close suggested edits. This could confuse the history of the doc, + and stop archives from looking read-only. + - In any case, archived documents would not be editable, and so revision + history could not be seen. +- Managing comments over time is infeasible. + - It's infeasible to point people to old comment threads, to suggest they + read and engage if they disagree with the original request. + - Even identifying _whether_ a comment led to a particular change is + infeasible. + - Comments vanish if the text they're on is removed. + - There is no way to quickly check for unresponded comments: instead, + authors will need to repeatedly crawl the doc. This is exacerbated by + process advice that the commenter be left to decide whether to resolve + comments, or slow-to-respond commenters. +- No support for seeing deltas. + - Only editors can see the delta. However, it should be expected that only + the author is an editor. + - Even if deltas were accessible, Docs delta support requires extra work + on the part of a doc editor to set up markers in the version history. +- Restricted support for extensibility. + - Proposals frequently have duplicated/boilerplate text that the authors + may need to rewrite in bulk, e.g. when renaming something. Google Docs + has built-in regex search. However, regex replace with capture groups + isn't directly supported, so users would need to learn and use Google + Apps Script to do the replacement. + - When URLs need to be replaced, Google Docs has _no_ support. Authors + must audit every URL. +- No low-friction support for formatted code blocks and inline code snippets. + - [Extensions exist](#google-docs-add-ons); we'll probably want to + recommend a specific extension to the community. +- Intra-document links break frequently, just from moving headers. + - It's also difficult to determine when an intra-document link is broken. + There doesn't seem to be support (built-in or add-on) for identifying + issues. + - It's also not supported to search through links, so even if the author + knows what they're breaking, they won't be able to find it. +- Google Docs comment syntax is essentially text-only. + - Syntax can interfere with "\*" insertion in code snippets due to bolding + confusion. +- May enhance Google-centric views of Carbon. + - Swift and Rust use Markdown-centric flows. +- Some companies may block Google Docs, because it's a file transfer service. + - It's unclear how prevalent this would be. GitHub may also be blocked + under similar security rules, but it's a requirement for participation + whereas Google Docs is avoidable. + - Ref: + [[1]](https://community.cisco.com/t5/web-security/blocking-google-docs/td-p/3376518), + [[2]](https://www.reddit.com/r/sysadmin/comments/2kwyhk/block_google_docs/), + [[3]](https://mybroadband.co.za/forum/threads/google-drive-blocked-at-work-work-around.809132/) +- Some individuals may refuse to use Google Docs over privacy (or other) + concerns. + - We've considered creating a GSuite domain for Carbon contributor + accounts to help address this. However, it may not address everyone's + concerns. #### Option: GitHub Markdown-centric flow ##### Overview -- Draft proposals: Markdown, possibly in Google Docs (but not required) -- Under review proposals: Markdown with review comments via GitHub -- Archive proposals: Markdown -- Final format: Markdown +- Draft proposals: Markdown, possibly in Google Docs (but not required) +- Under review proposals: Markdown with review comments via GitHub +- Archive proposals: Markdown +- Final format: Markdown ##### Flow summary For reviewing a proposal: -- Authors prepare a markdown doc using their favored tooling. - - This could be [a WYSIWYG markdown editor](#markdown-editing), or Google docs - for collaboration. -- Authors create a pull request with the markdown doc, to the carbon-proposals - GitHub repo. - - Community comments on the pull request. -- To move for a decision, no special action is taken. -- When a decision is reached, the review manager ensures the markdown doc is - updated appropriately and approves the pull request. +- Authors prepare a markdown doc using their favored tooling. + - This could be [a WYSIWYG markdown editor](#markdown-editing), or Google + docs for collaboration. +- Authors create a pull request with the markdown doc, to the carbon-proposals + GitHub repo. + - Community comments on the pull request. +- To move for a decision, no special action is taken. +- When a decision is reached, the review manager ensures the markdown doc is + updated appropriately and approves the pull request. If the proposal needs to be checked later to figure out why a decision was made: -- The committed markdown represents the final state of the proposal. -- The pull request may be viewed to read through comments, even after it is - merged. -- The pull request will have edit history publicly visible. - - GitHub has a nice renderer for markdown diffs. +- The committed markdown represents the final state of the proposal. +- The pull request may be viewed to read through comments, even after it is + merged. +- The pull request will have edit history publicly visible. + - GitHub has a nice renderer for markdown diffs. ##### Pros/Cons Pros: -- No need to convert file formats. - - Markdown reviews can be committed directly, putting all history in one - place. - - When dealing with a proposal that results in separate long-term - documentation, any differences between proposal text and long-term text will - be relatively easy to see in a diff. -- Access control is straightforward, determined by location. -- Referring to older comments is feasible. - - There may be some cases where comments disappear in certain situations, but - these problems should be avoidable. -- The archival copy of a document will include an easy link to comment history. -- Easy to see Markdown-formatted deltas in GitHub. -- The style of all documents can be updated centrally by changing a style sheet. -- Multiple comments may be sent together in a review. - - Comments may also be sent individually as in Docs. -- GitHub comment syntax supports Markdown, allowing code in comments. -- Multi-author editing is possible by using a shared GitHub branch as a source. - - This may still be less convenient than Google Docs flows, but multi-author - proposals could still use Google Docs to collaborate on the Markdown. +- No need to convert file formats. + - Markdown reviews can be committed directly, putting all history in one + place. + - When dealing with a proposal that results in separate long-term + documentation, any differences between proposal text and long-term text + will be relatively easy to see in a diff. +- Access control is straightforward, determined by location. +- Referring to older comments is feasible. + - There may be some cases where comments disappear in certain situations, + but these problems should be avoidable. +- The archival copy of a document will include an easy link to comment + history. +- Easy to see Markdown-formatted deltas in GitHub. +- The style of all documents can be updated centrally by changing a style + sheet. +- Multiple comments may be sent together in a review. + - Comments may also be sent individually as in Docs. +- GitHub comment syntax supports Markdown, allowing code in comments. +- Multi-author editing is possible by using a shared GitHub branch as a + source. + - This may still be less convenient than Google Docs flows, but + multi-author proposals could still use Google Docs to collaborate on the + Markdown. Neutral: -- Has a more difficult [suggested edit workflow](#suggesting-edits) than Google - Docs. - - For commenters, this may be a con, as it takes a little more work to add a - suggested edit. This may still lead to fewer suggested edits. - - For the author, this is a mixed bag: - - Whereas Google Docs may often see multiple, fragmented edits for the same - sentence, commenters would be more likely to suggest them together (a - pro). - - It's seamless to comment on changes, as it follows the normal comment - flow. - - It's seamless to make alternative edits and/or reject changes. - - The author may need to do extra reformatting/word wrapping after accepting - a Markdown change, which Docs would handle internally. - - For other readers, this is likely a pro: the current state of the doc - remains visible. +- Has a more difficult [suggested edit workflow](#suggesting-edits) than + Google Docs. + - For commenters, this may be a con, as it takes a little more work to add + a suggested edit. This may still lead to fewer suggested edits. + - For the author, this is a mixed bag: + - Whereas Google Docs may often see multiple, fragmented edits for the + same sentence, commenters would be more likely to suggest them + together (a pro). + - It's seamless to comment on changes, as it follows the normal + comment flow. + - It's seamless to make alternative edits and/or reject changes. + - The author may need to do extra reformatting/word wrapping after + accepting a Markdown change, which Docs would handle internally. + - For other readers, this is likely a pro: the current state of the doc + remains visible. Cons: -- GitHub comments on pull requests can be difficult to find in certain - situations. - - Comments can disappear when a pull request is rebased and force-pushed. - - Comments generally don't get tracked across revisions to a pull request. - - If we disallow force-pushes on pull requests, they are probably okay most of - the time. -- Can't comment on the rendered Markdown, only the raw Markdown. -- Images need to be stored separately from the main Markdown file. - - Final documentation may or may not need the images; they may only be added - to explain the proposal. i.e., this may be extra work without later benefit. +- GitHub comments on pull requests can be difficult to find in certain + situations. + - Comments can disappear when a pull request is rebased and force-pushed. + - Comments generally don't get tracked across revisions to a pull request. + - If we disallow force-pushes on pull requests, they are probably okay + most of the time. +- Can't comment on the rendered Markdown, only the raw Markdown. +- Images need to be stored separately from the main Markdown file. + - Final documentation may or may not need the images; they may only be + added to explain the proposal. i.e., this may be extra work without + later benefit. ## Details @@ -375,17 +383,17 @@ storage. Access controls: -- Managers: a minimal set (chandlerc + review managers?) to prevent accidental - edits. - - _Not_ the entire core team, in order to discourage the core team from using - privileges not accessible to the rest of the community (including - sub-teams). -- Content managers: the review manager group, so that they can archive - proposals. -- Contributors: none - does not provide sufficiently distinct access from - content managers. -- Commenters: full community -- Viewers: none +- Managers: a minimal set (chandlerc + review managers?) to prevent accidental + edits. + - _Not_ the entire core team, in order to discourage the core team from + using privileges not accessible to the rest of the community (including + sub-teams). +- Content managers: the review manager group, so that they can archive + proposals. +- Contributors: none - does not provide sufficiently distinct access from + content managers. +- Commenters: full community +- Viewers: none #### Proposals (shared folder) @@ -399,9 +407,9 @@ access from individual files. Access controls: -- Owner: chandlerc -- Editors: full community -- Commenters/viewers: none (non-public) +- Owner: chandlerc +- Editors: full community +- Commenters/viewers: none (non-public) #### Proposal Archive (folder in shared drive) @@ -415,7 +423,7 @@ be discouraged. Access controls: -- Inherited from Carbon language shared drive. +- Inherited from Carbon language shared drive. ### Google Docs proposal ACLs @@ -427,11 +435,11 @@ Google Docs is optional and may often be skipped. Access controls: -- Owner: proposal author (transferred to review manager, for proposals going to - decision) -- Editors: any collaborators -- Commenters: community -- Viewers: none +- Owner: proposal author (transferred to review manager, for proposals going + to decision) +- Editors: any collaborators +- Commenters: community +- Viewers: none ## Markdown-specific questions @@ -446,19 +454,19 @@ to the proposal archive. Access controls: -- Commit privileges: review managers +- Commit privileges: review managers Pros: -- Easy to find pending proposals; just look at the carbon-proposals issue - tracker. -- All proposals will be uniquely numbered. -- No need for a proposal label: everything's a proposal. +- Easy to find pending proposals; just look at the carbon-proposals issue + tracker. +- All proposals will be uniquely numbered. +- No need for a proposal label: everything's a proposal. Cons: -- Proposals affect other repos; may miss opportunities to combine changes. -- Harder to filter for proposals that are relevant to a specific repository. +- Proposals affect other repos; may miss opportunities to combine changes. +- Harder to filter for proposals that are relevant to a specific repository. #### Option: Store proposals in the repository they affect @@ -486,31 +494,32 @@ history. Access controls: -- Commit privileges: normal repository access, possibly with review managers - getting broad access in order to finalize proposals. +- Commit privileges: normal repository access, possibly with review managers + getting broad access in order to finalize proposals. Pros: -- Makes it easier to demonstrate the actual changes a proposal suggests making. -- Reduces possible redundant work by the author of making changes in two places - (the proposal, and affected documents). -- Keeps discussion about the _proposal_ and discussion about the _proposed - changes_ on a single review thread, for most cases. -- Makes it easy to find most/all proposals relevant to a given repository. +- Makes it easier to demonstrate the actual changes a proposal suggests + making. +- Reduces possible redundant work by the author of making changes in two + places (the proposal, and affected documents). +- Keeps discussion about the _proposal_ and discussion about the _proposed + changes_ on a single review thread, for most cases. +- Makes it easy to find most/all proposals relevant to a given repository. Cons: -- Proposals would need to be tracked separately per-repo. - - This could also end up being a pro if we get a bunch of different repos, as - it may become easier to find relevant proposals for a given repo. It's only - really a con for as long as we have few repos (which may last long-term, as - having many repos may lead to other scaling problems). -- Access controls are part of the parent repo, and so will be less restricted - than if we had a separate proposals repo. -- Proposals won't be uniquely numbered. - - We'll need to refer to proposals with the repo, e.g., `carbon-lang/456`. -- Need to make sure we have a proposal label, to separate from non-proposal - traffic. +- Proposals would need to be tracked separately per-repo. + - This could also end up being a pro if we get a bunch of different repos, + as it may become easier to find relevant proposals for a given repo. + It's only really a con for as long as we have few repos (which may last + long-term, as having many repos may lead to other scaling problems). +- Access controls are part of the parent repo, and so will be less restricted + than if we had a separate proposals repo. +- Proposals won't be uniquely numbered. + - We'll need to refer to proposals with the repo, e.g., `carbon-lang/456`. +- Need to make sure we have a proposal label, to separate from non-proposal + traffic. ### Open question: Should we push comments to focus on GitHub? @@ -518,9 +527,9 @@ Cons: #### Common principles -- Proposals will be declared on Discourse Forums at important stages; e.g., - asking for input on ideas, RFC, decisions, etc. -- Some discussion is expected to occur on the GitHub PR. +- Proposals will be declared on Discourse Forums at important stages; e.g., + asking for input on ideas, RFC, decisions, etc. +- Some discussion is expected to occur on the GitHub PR. #### Option: Push high-level comments to Discourse Forums @@ -529,20 +538,20 @@ Discourse Forums RFC. Pros: -- Discourse Forums offer better interfaces for pure, non-code-comment - discussion. -- Email notifications are easier to parse with less threading, more use of - quotes, and "In Reply To" automation. -- More familiar for people familiar with mixed Discourse/GitHub workflows. - - Both Rust and Swift use Discourse, and are closer to this option. - - May also be better for people used to using email lists to discuss proposed - changes. +- Discourse Forums offer better interfaces for pure, non-code-comment + discussion. +- Email notifications are easier to parse with less threading, more use of + quotes, and "In Reply To" automation. +- More familiar for people familiar with mixed Discourse/GitHub workflows. + - Both Rust and Swift use Discourse, and are closer to this option. + - May also be better for people used to using email lists to discuss + proposed changes. Cons: -- Leads contributors to two different places for comments - some high-level - discussion will inevitably be in GitHub. -- Contributors must read both Discourse Forums and GitHub to get context. +- Leads contributors to two different places for comments - some high-level + discussion will inevitably be in GitHub. +- Contributors must read both Discourse Forums and GitHub to get context. #### Option: Push high-level comments to GitHub @@ -551,30 +560,33 @@ discussion. Pros: -- The GitHub PR becomes a single hub for conversation. -- More familiar for people familiar with GitHub-only workflows. +- The GitHub PR becomes a single hub for conversation. +- More familiar for people familiar with GitHub-only workflows. Cons: -- Discourse Forum topics cannot have "create" without "reply" permissions, so - some high-level discussion will inevitably be in Discourse Forums. - - We could address this by only allowing moderators to post RFCs, but that may - be overly exclusive. -- Email notifications include only the lines of code affected, not what is being - replied to. This will generally make it infeasible to get context from emails. -- Comment threads sometimes make it unclear what's being replied to. e.g., - https://github.com/carbon-language/carbon-proposals/pull/5#discussion_r423401993 - and - ttps://github.com/carbon-language/carbon-proposals/pull/5/files/a51ff951561accfb4aee403d7add6e8e69009ce1#r423401993 - are equivalent, but the replied-to-comment is only visible in the file view. - - This may be particularly visible as an issue if high-level discussions are - often not line-specific. -- Not clear what to do about resolving high-level discussion comment threads. - - If comment threads are resolved, it's harder to read them, discouraging - third-party comment. - - If comment threads are not resolved, they may create a bunch of noise. As - noted above, GitHub manages the file view better than the discussion view. - - Mixed solutions will leave it to the author to choose the balance of issues. +- Discourse Forum topics cannot have "create" without "reply" permissions, so + some high-level discussion will inevitably be in Discourse Forums. + - We could address this by only allowing moderators to post RFCs, but that + may be overly exclusive. +- Email notifications include only the lines of code affected, not what is + being replied to. This will generally make it infeasible to get context from + emails. +- Comment threads sometimes make it unclear what's being replied to. e.g., + https://github.com/carbon-language/carbon-proposals/pull/5#discussion_r423401993 + and + ttps://github.com/carbon-language/carbon-proposals/pull/5/files/a51ff951561accfb4aee403d7add6e8e69009ce1#r423401993 + are equivalent, but the replied-to-comment is only visible in the file view. + - This may be particularly visible as an issue if high-level discussions + are often not line-specific. +- Not clear what to do about resolving high-level discussion comment threads. + - If comment threads are resolved, it's harder to read them, discouraging + third-party comment. + - If comment threads are not resolved, they may create a bunch of noise. + As noted above, GitHub manages the file view better than the discussion + view. + - Mixed solutions will leave it to the author to choose the balance of + issues. #### Option: Give no guidance, see what happens @@ -583,14 +595,14 @@ could offer no guidance. Pros: -- Less policies, more freedom. - - Discover what happens, switch back and forth over time based on individual - contributor preferences. +- Less policies, more freedom. + - Discover what happens, switch back and forth over time based on + individual contributor preferences. Cons: -- Pros of a primary hub are discarded. Cons of multiple hubs should be assumed - to remain. +- Pros of a primary hub are discarded. Cons of multiple hubs should be assumed + to remain. ### Open question: Should there be a tracking issue? @@ -598,9 +610,9 @@ Cons: #### Common principles -- Discourse Forum topics are minimally used to announce when a decision is going - to RFC, going to decision, and the decision once made. -- The proposal's PR may be used for discussion of the proposal. +- Discourse Forum topics are minimally used to announce when a decision is + going to RFC, going to decision, and the decision once made. +- The proposal's PR may be used for discussion of the proposal. #### Option: Tracking issue for all proposals @@ -609,25 +621,25 @@ In a workflow where there's always a tracking issue: 1. Create the tracking issue, e.g. #123. 2. Create the PR, e.g. #456, naming the proposal p0123.md after the tracking issue. - 1. Use GitHub features to link #123 and #456. + 1. Use GitHub features to link #123 and #456. 3. Update the status in p0123.md and labels of #123 when progressing a proposal. 4. When a decision is made, create a new PR, e.g. #789, containing the decision p0123-decision.md. - 2. This does not replace the Discourse Forum topic announcing a decision. - 3. Use GitHub features to link #123 and #789. - 4. Comments on the decision may go on the decision PR, similar to the - proposal PR discussion. + 2. This does not replace the Discourse Forum topic announcing a decision. + 3. Use GitHub features to link #123 and #789. + 4. Comments on the decision may go on the decision PR, similar to the + proposal PR discussion. 5. Declined/deferred proposals may be committed or not; it doesn't matter. Pros: -- Easy to find the full decision in p0123-decision.md. -- The PR to create the decision is clearly visible in the associated tracking - issue. +- Easy to find the full decision in p0123-decision.md. +- The PR to create the decision is clearly visible in the associated tracking + issue. Cons: -- The tracking issue separates more state. +- The tracking issue separates more state. #### Option: Don't require tracking issues @@ -636,34 +648,35 @@ may create them for bucketing work, they are non-essential): 1. Create the PR, e.g. #456, naming the proposal p0456.md. 2. Update the labels of #456 when progressing a proposal. - 1. Don't bother putting the status in p0456.md: people should rely on the PR - labels since it's in the same place. + 1. Don't bother putting the status in p0456.md: people should rely on the PR + labels since it's in the same place. 3. When a decision is made, add it as a comment to #456. - 2. This does not replace the Discourse Forum topic announcing a decision. - 3. Comments on the decision should go in Discourse Forums. - 4. The author is asked to link to the decision in p0456.md before the commit - is approved. + 2. This does not replace the Discourse Forum topic announcing a decision. + 3. Comments on the decision should go in Discourse Forums. + 4. The author is asked to link to the decision in p0456.md before the commit + is approved. 4. If declined/deferred proposals are committed, it would be best to add a status in p0456.md before committing. Pros: -- Lighter weight process: no tracking issue, and no need to update status in - p0456.md. +- Lighter weight process: no tracking issue, and no need to update status in + p0456.md. Cons: -- Harder to store the decision in a way that clearly links it to the original - proposal. - - In particular, finding discussion about the decision is hard to resolve. - Neither below ideas clearly improve on this, so preference to keep - everything in Discourse Forum topic. - - Could in theory have the full decision in p0456.md. Pro is it's easy to - find, con is it makes it look more like the author's writing the decision. - - Could keep storing p0456-decision.md. Pro is it's easy to find, con is the - lack of association with #456 and extra file+PR. Not clear that storage - offers enough independent value to justify. -- Restricts where discussion about a decision should occur. +- Harder to store the decision in a way that clearly links it to the original + proposal. + - In particular, finding discussion about the decision is hard to resolve. + Neither below ideas clearly improve on this, so preference to keep + everything in Discourse Forum topic. + - Could in theory have the full decision in p0456.md. Pro is it's easy to + find, con is it makes it look more like the author's writing the + decision. + - Could keep storing p0456-decision.md. Pro is it's easy to find, con is + the lack of association with #456 and extra file+PR. Not clear that + storage offers enough independent value to justify. +- Restricts where discussion about a decision should occur. ### Open question: Should declined/deferred proposals be committed? @@ -671,10 +684,10 @@ Cons: #### Common principles -- Accepted proposals are always committed. -- We may (or may not) commit decisions for any committed proposal (accepted or - otherwise). - - See notes in the above open question. +- Accepted proposals are always committed. +- We may (or may not) commit decisions for any committed proposal (accepted or + otherwise). + - See notes in the above open question. #### Option: Do not commit declined/deferred proposals @@ -686,14 +699,14 @@ coming from a fork. Pros: -- The proposals directory remains a list of only accepted proposals. -- No need to spend effort saving declined/deferred proposals. +- The proposals directory remains a list of only accepted proposals. +- No need to spend effort saving declined/deferred proposals. \ Cons: -- Lose an easy way to check declined/deferred proposals for history. - - More reliance on searching forums for history. +- Lose an easy way to check declined/deferred proposals for history. + - More reliance on searching forums for history. #### Option: Commit declined/deferred proposals @@ -701,13 +714,13 @@ Under this approach, declined/deferred proposals are committed. Pros: -- Easy to skim through declined/deferred proposals. +- Easy to skim through declined/deferred proposals. Cons: -- Finding accepted proposals may become more difficult. - - Could put declined/deferred proposals in a different directory. -- Requires a little more effort in order to save declined/deferred proposals. +- Finding accepted proposals may become more difficult. + - Could put declined/deferred proposals in a different directory. +- Requires a little more effort in order to save declined/deferred proposals. ## Alternatives considered @@ -717,9 +730,9 @@ Instead of adding a shared folder for proposals, we could instead use a shared drive for everything. However, this puts us in a bad situation for taking in new proposals. We would need to choose between: -- Allowing **all** community member edit access to **all** proposals. -- Requiring authors ask a review manager to create a blank proposal for them to - edit. +- Allowing **all** community member edit access to **all** proposals. +- Requiring authors ask a review manager to create a blank proposal for them + to edit. Neither of these feel like great situations - they are either overly-broad or overly-restrictive sharing, neither approximating what we actually would want, @@ -793,11 +806,11 @@ Google's internal-only equivalent. I'm not seeing obvious downsides. Pros: -- Provides easy conversion of Google Docs to Markdown. +- Provides easy conversion of Google Docs to Markdown. Cons: -- ? +- ? #### Code blocks @@ -809,14 +822,14 @@ do some syntax highlighting, whereas Code blocks does none. Pros: -- Public code formatting. -- Works with "Docs to Markdown" plugin to get ```-block escaping. +- Public code formatting. +- Works with "Docs to Markdown" plugin to get ```-block escaping. Cons: -- Mediocre syntax highlighting for Carbon. -- No inline `foo` highlighting, unlike Google's internal-only equivalent. -- Different highlighting from that in the eventual Markdown document. +- Mediocre syntax highlighting for Carbon. +- No inline `foo` highlighting, unlike Google's internal-only equivalent. +- Different highlighting from that in the eventual Markdown document. #### Advanced Find & Replace @@ -827,13 +840,13 @@ features, particularly around URL and regexp support. Pros: -- Offers improved functionality around key Google Docs friction problems. +- Offers improved functionality around key Google Docs friction problems. Cons: -- 2 of 5 stars: we should not expect quality. -- \$6 purchase price may turn off contributors. -- Requires permissions that are banned by Google internally. +- 2 of 5 stars: we should not expect quality. +- \$6 purchase price may turn off contributors. +- Requires permissions that are banned by Google internally. ### Markdown editing @@ -849,15 +862,15 @@ simply one option amongst many, and not necessarily the best. Pros: -- Provides preview when editing Markdown files. -- Provides application-specific comment support. +- Provides preview when editing Markdown files. +- Provides application-specific comment support. Cons: -- Cannot use shared Google workspaces with Google corp accounts, due to security - restrictions. Will likely cause issues for others, too. -- Google Docs only works as passive storage. - - StackEdit docs aren't Google Docs, comments aren't Google Docs comments. +- Cannot use shared Google workspaces with Google corp accounts, due to + security restrictions. Will likely cause issues for others, too. +- Google Docs only works as passive storage. + - StackEdit docs aren't Google Docs, comments aren't Google Docs comments. ### GitHub Markdown syntax highlighting diff --git a/proposals/p0051.md b/proposals/p0051.md index 7ffe58cb3c39..f0793f3ebb5f 100644 --- a/proposals/p0051.md +++ b/proposals/p0051.md @@ -12,17 +12,17 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception -- [Problem](#problem) -- [Background](#background) -- [Proposal](#proposal) - - [Including success criteria](#including-success-criteria) -- [Alternatives](#alternatives) - - [Change priority of interoperability and migration](#change-priority-of-interoperability-and-migration) - - [Address project goals differently](#address-project-goals-differently) - - [Status quo](#status-quo) - - [Completely remove the community priority from this document](#completely-remove-the-community-priority-from-this-document) - - [Add project goals to the priority list](#add-project-goals-to-the-priority-list) - - [Merge project goals and language goals](#merge-project-goals-and-language-goals) +- [Problem](#problem) +- [Background](#background) +- [Proposal](#proposal) + - [Including success criteria](#including-success-criteria) +- [Alternatives](#alternatives) + - [Change priority of interoperability and migration](#change-priority-of-interoperability-and-migration) + - [Address project goals differently](#address-project-goals-differently) + - [Status quo](#status-quo) + - [Completely remove the community priority from this document](#completely-remove-the-community-priority-from-this-document) + - [Add project goals to the priority list](#add-project-goals-to-the-priority-list) + - [Merge project goals and language goals](#merge-project-goals-and-language-goals) @@ -59,8 +59,8 @@ principle. This proposal includes [success criteria](/docs/project/principles/success_criteria.md) covering: -- Platforms -- Migration tooling +- Platforms +- Migration tooling It should be expected that more will be added in the future. @@ -95,56 +95,56 @@ Overall, we would present the pros and cons as: Pros: -- There is a consensus that interoperability is critical. Making it the top goal - emphasizes that. +- There is a consensus that interoperability is critical. Making it the top + goal emphasizes that. Cons: -- While interoperability is critical, the same is true of other goals; this - isn't enough to determine priority. -- There are trade-offs between goals where there is already a consensus that - inteoperability will be diminished in favor of other goals, and there aren't - as many clear cases in the other direction. - - Taken to extremes, making interoperability and migration a higher priority - than evolution would suggest that Carbon should start with C++ and - incrementally evolve from that base. We have observed areas where C++ has - had trouble evolving, and Carbon would risk getting stuck on similar local - maxima in order to avoid breaking existing code. +- While interoperability is critical, the same is true of other goals; this + isn't enough to determine priority. +- There are trade-offs between goals where there is already a consensus that + inteoperability will be diminished in favor of other goals, and there aren't + as many clear cases in the other direction. + - Taken to extremes, making interoperability and migration a higher + priority than evolution would suggest that Carbon should start with C++ + and incrementally evolve from that base. We have observed areas where + C++ has had trouble evolving, and Carbon would risk getting stuck on + similar local maxima in order to avoid breaking existing code. For example of where trade-offs may be seen right now: -- Carbon's set of primitive types won't match C++'s list; we currently expect - multiple C++ types to map to single Carbon types. This could be considered a - conflict with multiple priorities: - - #2: Carbon's leaning for fewer types should make evolution of the language - easier. - - #3: Carbon code will be easier to read and understand with fewer types. -- When considering `Int` vs `int`, Carbon's plans do not mirror C++. This could - be considered a conflict with multiple priorities: - - #1: Carbon's primary types, such as `Int`, should be allowed to replace - C++-specified overflow behaviors with alternatives that are higher - performance. - - #3: Avoiding platform-specific types should make it easier to understand how - could will function on various platforms. - - #4: Carbon's plan for `Int` trapping where C++ would overflow should make - code safety easier. -- We expect platform support priorities to differ between C/C++ and Carbon. This - is a conflict with Carbon's #6 priority, which focuses support on modern over - legacy platforms. -- C++'s preprocessor macros will be replaced by metaprogramming in Carbon. It's - not clear what migration of code using macros will look like, but some will - likely be expanded by automation. This could be considered a conflict with - multiple priorities: - - #2: Structured metaprogramming should make it easier to evolve software. - - #3: Metaprogramming should be easier to read than preprocessor macros. -- Templates have been argued as only being added for interoperability/migration, - and that we could only have generics without that goal. This is not considered - a conflict between goal priorities. - - This could be considered a conflict with priority #3, because templates are - hard to read and understand. However, templates don't constrain other parts - of the language. While they may have readability or other problems, they - aren't core or required in the way that other elements are, including - primitive types. +- Carbon's set of primitive types won't match C++'s list; we currently expect + multiple C++ types to map to single Carbon types. This could be considered a + conflict with multiple priorities: + - #2: Carbon's leaning for fewer types should make evolution of the + language easier. + - #3: Carbon code will be easier to read and understand with fewer types. +- When considering `Int` vs `int`, Carbon's plans do not mirror C++. This + could be considered a conflict with multiple priorities: + - #1: Carbon's primary types, such as `Int`, should be allowed to replace + C++-specified overflow behaviors with alternatives that are higher + performance. + - #3: Avoiding platform-specific types should make it easier to understand + how could will function on various platforms. + - #4: Carbon's plan for `Int` trapping where C++ would overflow should + make code safety easier. +- We expect platform support priorities to differ between C/C++ and Carbon. + This is a conflict with Carbon's #6 priority, which focuses support on + modern over legacy platforms. +- C++'s preprocessor macros will be replaced by metaprogramming in Carbon. + It's not clear what migration of code using macros will look like, but some + will likely be expanded by automation. This could be considered a conflict + with multiple priorities: + - #2: Structured metaprogramming should make it easier to evolve software. + - #3: Metaprogramming should be easier to read than preprocessor macros. +- Templates have been argued as only being added for + interoperability/migration, and that we could only have generics without + that goal. This is not considered a conflict between goal priorities. + - This could be considered a conflict with priority #3, because templates + are hard to read and understand. However, templates don't constrain + other parts of the language. While they may have readability or other + problems, they aren't core or required in the way that other elements + are, including primitive types. ### Address project goals differently @@ -169,14 +169,14 @@ We could completely remove the project goals from this document. Pros: -- Allows this to be the "language goals" document. +- Allows this to be the "language goals" document. Cons: -- Creates additional documents that need to be understood to parse language - goals. -- Makes for less clear prioritization of community, increasing ambiguity on how - community vs language design conflicts can be resolved. +- Creates additional documents that need to be understood to parse language + goals. +- Makes for less clear prioritization of community, increasing ambiguity on + how community vs language design conflicts can be resolved. #### Add project goals to the priority list @@ -184,15 +184,15 @@ We could make the project goals part of the priority list. Pros: -- Makes the ordering unambiguous. +- Makes the ordering unambiguous. Cons: -- Makes what's currently a numerated list of language design goals less - design-focused. -- Prevents saying trivial things like "performance is our top priority". - - Unless community isn't the top priority, re-creating the conflict risk that - led to the creating of these project goals. +- Makes what's currently a numerated list of language design goals less + design-focused. +- Prevents saying trivial things like "performance is our top priority". + - Unless community isn't the top priority, re-creating the conflict risk + that led to the creating of these project goals. #### Merge project goals and language goals @@ -201,11 +201,12 @@ project goals and language goals. Pros: -- Makes the document shorter and more concise. -- Tooling can already be considered a priority under "Code that is easy to read, - understand, and write", and is explicitly mentioned as part of that goal. +- Makes the document shorter and more concise. +- Tooling can already be considered a priority under "Code that is easy to + read, understand, and write", and is explicitly mentioned as part of that + goal. Cons: -- Previous setup raised objections over why the community goal wasn't part of - the priority list. +- Previous setup raised objections over why the community goal wasn't part of + the priority list. diff --git a/proposals/p0074-decision.md b/proposals/p0074-decision.md index e0621a7bce25..fa884409d8f8 100644 --- a/proposals/p0074-decision.md +++ b/proposals/p0074-decision.md @@ -10,17 +10,17 @@ Proposal accepted on 2020-06-02 Affirming: -- [austern](https://github.com/austern) -- [chandlerc](https://github.com/chandlerc) -- [geoffromer](https://github.com/geoffromer) -- [gribozavr](https://github.com/gribozavr) -- [josh11b](https://github.com/josh11b) -- [tituswinters](https://github.com/tituswinters) -- [zygoloid](https://github.com/zygoloid) +- [austern](https://github.com/austern) +- [chandlerc](https://github.com/chandlerc) +- [geoffromer](https://github.com/geoffromer) +- [gribozavr](https://github.com/gribozavr) +- [josh11b](https://github.com/josh11b) +- [tituswinters](https://github.com/tituswinters) +- [zygoloid](https://github.com/zygoloid) Abstaining: -- [noncombatant](https://github.com/noncombatant) +- [noncombatant](https://github.com/noncombatant) ## Open questions @@ -31,10 +31,11 @@ that can be resolved by review managers as part of doc changes. ## Rationale -- This directly supports our community goals: not everybody is in a position to - respond to events with less than a day of latency, so longer lead times before - deadlines will help enable them to participate. - - Longer lead time makes it more likely that we'll get substantive comments. -- The answer to the open question doesn't strongly matter, and there is a - preference for leaving it to the review managers' discretion rather than - having the core team decide. +- This directly supports our community goals: not everybody is in a position + to respond to events with less than a day of latency, so longer lead times + before deadlines will help enable them to participate. + - Longer lead time makes it more likely that we'll get substantive + comments. +- The answer to the open question doesn't strongly matter, and there is a + preference for leaving it to the review managers' discretion rather than + having the core team decide. diff --git a/proposals/p0074.md b/proposals/p0074.md index a2eeb3437700..8cff57ccb7ce 100644 --- a/proposals/p0074.md +++ b/proposals/p0074.md @@ -12,14 +12,14 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception -- [Problem](#problem) -- [Background](#background) -- [Proposal](#proposal) -- [Details](#details) - - [Open Question/Bikeshed](#open-questionbikeshed) -- [Alternatives considered](#alternatives-considered) - - [Alternative 1](#alternative-1) - - [Alternative 2](#alternative-2) +- [Problem](#problem) +- [Background](#background) +- [Proposal](#proposal) +- [Details](#details) + - [Open Question/Bikeshed](#open-questionbikeshed) +- [Alternatives considered](#alternatives-considered) + - [Alternative 1](#alternative-1) + - [Alternative 2](#alternative-2) @@ -58,17 +58,17 @@ during the review period rather than the decision period. ## Details -- A deadline for final comments will be published at least 7 calendar days (or 4 - working days, if longer) in advance (instead of the current 1 day). On or - before the deadline date, the deadline may be extended if the review manager - determines that there is still productive discussion going on. - - At the time the comment period deadline is announced, the proposal will be - added to the agenda of the next core team meeting following the comment - period deadline. -- There must be a minimum of four working days between the end of the comment - period and the day of the meeting. - - If the deadline for comments is extended, the agenda item will be moved, if - necessary, by the review manager. +- A deadline for final comments will be published at least 7 calendar days (or + 4 working days, if longer) in advance (instead of the current 1 day). On or + before the deadline date, the deadline may be extended if the review manager + determines that there is still productive discussion going on. + - At the time the comment period deadline is announced, the proposal will + be added to the agenda of the next core team meeting following the + comment period deadline. +- There must be a minimum of four working days between the end of the comment + period and the day of the meeting. + - If the deadline for comments is extended, the agenda item will be moved, + if necessary, by the review manager. ### Open Question/Bikeshed diff --git a/proposals/template-decision.md b/proposals/template-decision.md index 5cd39e8aecd0..1c17a015b865 100644 --- a/proposals/template-decision.md +++ b/proposals/template-decision.md @@ -10,14 +10,14 @@ Proposal accepted on 2020-MM-DD Affirming: -- [austern](https://github.com/austern) -- [chandlerc](https://github.com/chandlerc) -- [geoffromer](https://github.com/geoffromer) -- [gribozavr](https://github.com/gribozavr) -- [josh11b](https://github.com/josh11b) -- [noncombatant](https://github.com/noncombatant) -- [tituswinters](https://github.com/tituswinters) -- [zygoloid](https://github.com/zygoloid) +- [austern](https://github.com/austern) +- [chandlerc](https://github.com/chandlerc) +- [geoffromer](https://github.com/geoffromer) +- [gribozavr](https://github.com/gribozavr) +- [josh11b](https://github.com/josh11b) +- [noncombatant](https://github.com/noncombatant) +- [tituswinters](https://github.com/tituswinters) +- [zygoloid](https://github.com/zygoloid) Abstaining: @@ -29,4 +29,4 @@ TODO answer. ## Rationale -- TODO +- TODO diff --git a/proposals/template.md b/proposals/template.md index edc51d50b99b..72007d0a76b5 100644 --- a/proposals/template.md +++ b/proposals/template.md @@ -12,12 +12,12 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception -- [TODO: Initial proposal setup](#todo-initial-proposal-setup) -- [Problem](#problem) -- [Background](#background) -- [Proposal](#proposal) -- [Details](#details) -- [Alternatives considered](#alternatives-considered) +- [TODO: Initial proposal setup](#todo-initial-proposal-setup) +- [Problem](#problem) +- [Background](#background) +- [Proposal](#proposal) +- [Details](#details) +- [Alternatives considered](#alternatives-considered) @@ -27,7 +27,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 1. Copy this template to `new.md`, and create a commit. 2. Create a GitHub pull request, to get a pull request number. - - Add the `proposal` and `WIP` labels to the pull request. + - Add the `proposal` and `WIP` labels to the pull request. 3. Rename `new.md` to `/proposals/p####.md`, where `####` should be the pull request number. 4. Update the title of the proposal (the `TODO` on line 1). diff --git a/src/scripts/pre-commit-proposal-list.py b/src/scripts/pre-commit-proposal-list.py index c5cf4a7c6490..66490f1886b9 100755 --- a/src/scripts/pre-commit-proposal-list.py +++ b/src/scripts/pre-commit-proposal-list.py @@ -38,11 +38,11 @@ if __name__ == "__main__": print("ERROR: %s doesn't have a title on the first line." % file) error = True proposals.append( - "- [%s - %s](%s)" % (file_match[1], title_match[1], file) + "- [%s - %s](%s)" % (file_match[1], title_match[1], file) ) decision_file = "p%s-decision.md" % file_match[1] if os.path.exists(os.path.join(proposal_dir, decision_file)): - proposals.append(" - [Decision](%s)" % decision_file) + proposals.append(" - [Decision](%s)" % decision_file) # We print batched errors for usability, but still need to exit with # failure. if error: diff --git a/src/scripts/pre-commit-toc.js b/src/scripts/pre-commit-toc.js index 23a4f310aa67..b27037bf8f14 100755 --- a/src/scripts/pre-commit-toc.js +++ b/src/scripts/pre-commit-toc.js @@ -46,8 +46,10 @@ for (var i = 0; i < files.length; ++i) { continue; } - // Do the toc substitution. - newContent = mdtoc.insert(newContent, { bullets: '-' }); + // Do the toc substitution. Resulting indents will look like: + // - H1 + // - H2 + newContent = mdtoc.insert(newContent, { indent: ' ', bullets: '- ' }); if (oldContent != newContent) { console.log(`Updating ${file}`);