From d667088e809b8d4bf7f461bbe0d61791d0b92738 Mon Sep 17 00:00:00 2001 From: jonmeow <46229924+jonmeow@users.noreply.github.com> Date: Wed, 13 May 2020 11:08:30 -0700 Subject: [PATCH 01/11] Create a carbon-lang version of the proposal tracking proposal. --- proposals/README.md | 4 + proposals/p0001.md | 618 ++++++++++++++++++++++++++++++++++++++++++ proposals/template.md | 51 ++++ 3 files changed, 673 insertions(+) create mode 100644 proposals/README.md create mode 100644 proposals/p0001.md create mode 100644 proposals/template.md diff --git a/proposals/README.md b/proposals/README.md new file mode 100644 index 0000000000000..df21aab11459b --- /dev/null +++ b/proposals/README.md @@ -0,0 +1,4 @@ +This directory contains all proposals for the carbon-lang repo. Files will be +named `p####.md`, where `####` is the corresponding tracking issue. They may +have associated subdirectories named `p####` which contain related files (e.g., +images) for the proposal. diff --git a/proposals/p0001.md b/proposals/p0001.md new file mode 100644 index 0000000000000..92ad90b1f7f77 --- /dev/null +++ b/proposals/p0001.md @@ -0,0 +1,618 @@ + + +# Carbon: Proposal tracking + +- **Authors:** jperkins@google.com +- **[Tracking issue](https://github.com/carbon-language/carbon-proposals/issues/1)** +- **Status:** RFC +- **Created:** 2020-04-08 + +**_PLEASE_ DO NOT SHARE OUTSIDE CARBON FORUMS** + +## Problem + +How should we: + +- 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. + +## Background + +One thing that is _not_ under question is that we will have accepted proposals +in Markdown. This is critical, as we are essentially only delaying when a +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? + +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 +license attached. + +Although the evolution document currently makes statements about how to manage +proposals, changes in approval from this doc may affect the evolution process. +Explicit wording changes aren't outlined here because they are assumed to be +part of executing this proposal rather than the substance of this proposal. + +For reference, a version of this proposal is also available in +[Google Docs](https://docs.google.com/document/d/1LSR63t3MU4iGvwJKGQwYVH_BToziRAKTCOCdZYItOEw/edit#). + +## Proposal + +### Overview + +This proposal presents two possible flows: one Google Docs-centric, one +Markdown-centric. This is an open question. + +In either case, it's assumed that we will want a Carbon language shared drive +for any Google Docs we may create, and a Proposal archive GitHub repo. + +### Open question: do we use a Google Docs-centric or GitHub Markdown-centric flow? + +All documents will end up in Markdown. Some members of the core team have a +stated preference for reviewing proposals in Google Docs, and some have a +preference for Markdown. No other clear options exist. This would yield two +possible flows: + +#### Option: Google Docs-centric flow + +##### Overview + +- 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. + +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. + +##### 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. + +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. + +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](https://docs.google.com/document/d/1pm_NgSVmitTAP4b784RV-wDe7wR-0Ml6l1qan0iWENw/edit#heading=h.l755sd9irx3w); + 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 concerns. + - We've considered creating a GSuite domain for Carbon documentation 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 + +##### 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. + +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. + +##### 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. + +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. + +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. + +## Details + +### Carbon language shared drive + +#### Main shared drive + +A shared drive will be used as a nexus for any Google Docs materials. This +mainly offers a central point for contributors to locate materials, as most will +not be able to modify contents. + +A shared drive should be assumed to be present, regardless of whether we choose +a Google Docs-centric flow: if we allow/encourage the use of Google Docs for +collaborative editing in a Markdown-centric flow, we should still provide +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 + +#### Proposals (shared folder) + +Community members need to be able to add proposals to the shared folder. This +will be available as a shortcut from the main shared drive. + +In shared folders, edit access to the folder allows adding/moving/removing +files, but doesn't grant control over the actual _file_, which is still owned by +the individual creator. Unlike shared drives, proposal authors can remove edit +access from individual files. + +Access controls: + +- Owner: chandlerc +- Editors: full community +- Commenters/viewers: none (non-public) + +#### Proposal Archive (folder in shared drive) + +The archive will be used to store reviewed proposals. This will mainly make +comments on proposals available for future reference. + +To allow viewing comments, comment access _must_ be granted: Google Docs +comments are not visible to users with view-only access. At the same time, this +means contributors will still be able to comment on archived docs: this should +be discouraged. + +Access controls: + +- Inherited from Carbon language shared drive. + +### Google Docs proposal ACLs + +In this setup, pending proposals go into the Proposals shared folder, where +they'll still have their own ACLs. + +Note that, in the Markdown-centric flow, this is generally not relevant: using +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 + +### Open question: Where should proposals be stored in GitHub? + +#### Option: Proposal archive GitHub repo (carbon-proposals) + +In this approach, the review managers are presumed to be responsible for commits +to the proposal archive. + +Access controls: + +- Commit privileges: review managers + +Pros: + +- Easy to find pending proposals; just look at the carbon-proposals issue + tracker. + +Cons: + +- Proposals affect other repos; may miss opportunities to combine changes. + +#### Option: Store proposals in the repository they affect + +In this approach, we would store proposals in the same repository as they +affect. e.g., a proposal about the spec would be stored in carbon-lang, while a +proposal specific to the compiler would be in carbon-toolchains. If a proposal +affected multiple repositories, we'd probably choose a single primary repository +for the proposal. + +Specific to a GitHub Markdown-centric flow, we could additionally allow the +proposal's pull request to include the specific proposed changes to +documentation where appropriate, allowing for the author to avoid duplicating +text in the proposal itself. + +We would likely still want a proposal document with a summary at a minimum, even +for small proposals. The summary can link to the pull request for details, +creating additional breadcrumbs for reading the full (with additional document +edits) proposal. + +Rejected proposals should commit _only_ the proposal document. A link to the +pull request in the proposal document should make it easier to research +rejections. Alternatively, rejected proposals could have their pull request +abandoned, but that would leave only the tracking issue as a breadcrumb for +history. + +Access controls: + +- 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. + +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 while we're a small project. +- Access controls are part of the parent repo, and so will be less restricted + than if we had a separate proposals repo. + +## Alternatives considered + +### Use a shared drive for everything + +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. + +Neither of these feel like great situations - they are either overly-broad or +overly-restrictive sharing, neither approximating what we actually would want, +which is for anybody in the community to easily create proposals. + +## Appendix + +### General concern about multiple Markdown flavors + +Different markdown implementations have subtly different rendering rules for the +same input. e.g., per [CommonMark Spec](https://spec.commonmark.org/0.29/#), +table syntax is not specified, although +[GitHub uses a table extension](https://guides.github.com/features/mastering-markdown/). +However, we do plan on using GitHub consistently; this only stands to confuse +users of other Markdown systems. + +Choosing the Google Docs-centric flow does not eliminate this issue, since +proposals will be archived in Markdown either way. + +### Google Docs vs GitHub comment flow comparison + +#### Comment clustering + +Google Docs only allows sending comments individually. + +GitHub supports either sending comments individually or clustering multiple +comments together, as in a review. + +#### Basic comments + +[Google Docs](https://support.google.com/docs/answer/65129?co=GENIE.Platform%3DDesktop&hl=en): + +1. Follow the link to the doc +2. Select text to comment on +3. Click on "+" to add a comment (or use keyboard shortcut) +4. Enter text +5. Click "Comment" + +[GitHub](https://help.github.com/en/enterprise/2.14/user/articles/commenting-on-a-pull-request): + +1. Follow the link to a pull request +2. Click on "+" next to line to comment on +3. Enter text +4. Click "Add single comment" + +#### Suggesting edits + +[Google Docs](https://support.google.com/docs/answer/6033474?co=GENIE.Platform%3DDesktop&hl=en): + +1. Follow the link to the doc +2. Select text to suggest edit on +3. Type suggested edit + +[GitHub](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request): + +1. Follow the link to a pull request +2. Click on "+" next to line to comment on +3. Optionally select multiple lines +4. Click on the left-most icon, a doc with a "+" on it +5. Edit quoted text +6. Click "Add single comment" + +### Google Docs add-ons + +#### Docs to Markdown + +[https://gsuite.google.com/marketplace/app/docs_to_markdown/700168918607](https://gsuite.google.com/marketplace/app/docs_to_markdown/700168918607) + +This plugin actually looks pretty good, and may actually work better than +Google's internal-only equivalent. I'm not seeing obvious downsides. + +Pros: + +- Provides easy conversion of Google Docs to Markdown. + +Cons: + +- ? + +#### Code blocks + +[https://gsuite.google.com/marketplace/app/code_blocks/100740430168](https://gsuite.google.com/marketplace/app/code_blocks/100740430168) + +This is another code formatting tool. However, by default it doesn't do much +syntax highlighting for example Carbon code; we'd need to see if a language has +sufficiently close syntax to do okay. + +For comparison, here's a snippet showing GitHub results: + +``` +template fn Convert[Type:$ T](T: source, Type:$ U) -> U { + var U: converted = source; + return converted; +} + +fn Foo(Int: i) -> Float { + return Convert(i, Float); +} +``` + +Pros: + +- 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. + +#### Advanced Find & Replace + +[https://gsuite.google.com/marketplace/app/advanced_find_replace/11210842879?pann=cwsdp&hl=en-US](https://gsuite.google.com/marketplace/app/advanced_find_replace/11210842879?pann=cwsdp&hl=en-US) + +Advanced Find & Replace offers more advanced functionality than the built-in +features, particularly around URL and regexp support. + +Pros: + +- 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. + +### Markdown editing + +There are multiple markdown editing tools. + +#### StackEdit + +[https://stackedit.io/](https://stackedit.io/) + +StackEdit may look good on the surface, but we may effectively be restricted to +using it as a WYSYWIG markdown editor, not for collaboration. For that, it's +simply one option amongst many, and not necessarily the best. + +Pros: + +- 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. + +### GitHub Markdown syntax highlighting + +GitHub's syntax highlighter +[allows adding third-party extensions](https://github.com/github/linguist/blob/master/CONTRIBUTING.md#adding-an-extension-to-a-language), +but requires them to have significant use. + +Note we can't take advantage of this until Carbon is public. We may be able to +find a language with sufficiently similar syntax to +[override the language](https://github.com/github/linguist/#overrides) and get +reasonable highlighting. diff --git a/proposals/template.md b/proposals/template.md new file mode 100644 index 0000000000000..69cef4313f2b3 --- /dev/null +++ b/proposals/template.md @@ -0,0 +1,51 @@ + + +# TODO: Initial proposal setup + +1. Create a GitHub tracking issue in this repo using + [the template](https://github.com/carbon-language/carbon-lang/issues/new?template=proposal.md). +2. Prepare a pull request with the proposal, and add a link to it on the + tracking issue. + - Although you may want to add more files to the pull request later, most + proposals will be very bare at this point. +3. Delete this section. + +TODOs indicate where content should be updated for a proposal. See +[Carbon Governance and Evolution](https://github.com/carbon-language/carbon-lang/blob/master/docs/project/evolution.md) +for more details. + +# Carbon: TODO + +- **Authors:** TODO +- **[Tracking issue](https://github.com/carbon-language/carbon-lang/issues/TODO)** +- **Status:** RFC +- **Created:** 2020-MM-DD (TODO) + +**_PLEASE_ DO NOT SHARE OUTSIDE CARBON FORUMS** + +## Problem + +TODO: What problem are you trying to solve? How important is that problem? Who +is impacted by it? + +## Background + +TODO: Is there any background that readers should consider to fully understand +this problem and your approach to solving it? + +## Proposal + +TODO: Briefly and at a high level, how do you propose to solve the problem? Why +will that in fact solve it? + +## Details + +TODO: Fully explain the details of the proposed solution. + +## Alternatives considered + +TODO: What alternative solutions have you considered? From 1209b7d18f826fb04357eff70299518311bce6a8 Mon Sep 17 00:00:00 2001 From: jonmeow <46229924+jonmeow@users.noreply.github.com> Date: Wed, 13 May 2020 11:09:19 -0700 Subject: [PATCH 02/11] More files --- docs/project/commenting_guidelines.md | 25 +- docs/project/consensus_decision_making.md | 22 +- docs/project/evolution.md | 278 ++++++++++++---------- 3 files changed, 173 insertions(+), 152 deletions(-) diff --git a/docs/project/commenting_guidelines.md b/docs/project/commenting_guidelines.md index 4a2844ef8f9a0..e8feb47f56753 100644 --- a/docs/project/commenting_guidelines.md +++ b/docs/project/commenting_guidelines.md @@ -17,18 +17,19 @@ always try to keep feedback, even when critical, constructive and supportive. suggested action, and the expected result from that action. The more specific a comment is, the easier it will be for the proposal author to evaluate. - - Objections to specific phrasing should suggest alternative phrasing. - -- **Use Discourse Forums for long comments.** If a Google Doc comment would be - over two paragraphs, take it to the Discourse Forum topic. Doc comments are - good for quick, short feedback; detailed feedback is better shared on - Discourse Forums. - - - Use the forum topic created by the author, rather than creating a new topic. - It needs to be easy for authors and other reviewers to find comments. - - If your comment represents a significant change to the doc, include a list - of pros and cons. Even if the author disagrees with the change, they can use - those to document the alternative. + - Objections to specific phrasing should suggest alternative phrasing. + +- **Use Discourse Forums for long comments.** GitHub is good for + short-to-moderate-sized comments. Discourse Forums is better for long, + detailed comments, particularly where multiple parties may get involved in + discussion. + + - Use the forum topic created by the author, rather than creating a new + topic. It needs to be easy for authors and other reviewers to find + comments. + - If your comment represents a significant change to the doc, include a + list of pros and cons. Even if the author disagrees with the change, they + can use those to document the alternative. - **Be supportive in your criticism.** The author may be receiving many comments, and we want to keep contributors motivated to respond. diff --git a/docs/project/consensus_decision_making.md b/docs/project/consensus_decision_making.md index 947364d6fc0d4..10580a82f32aa 100644 --- a/docs/project/consensus_decision_making.md +++ b/docs/project/consensus_decision_making.md @@ -56,15 +56,15 @@ 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. + - 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. + - 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 @@ -103,9 +103,9 @@ items, meetings will not be held. Agenda items (e.g., proposals) should be added at least one week in advance (or four working days, if longer), so that members have time to review items added to the agenda. Sub-items (e.g., proposal discussion points) should be added at -least one day before the meeting; every open Google Doc comment is implicitly a -sub-item. Please feel free to add items to the agenda and remove them later if -the agenda item is resolved over other communication forums. +least one day before the meeting; every open GitHub pull request comment is +implicitly a sub-item. Please feel free to add items to the agenda and remove +them later if the agenda item is resolved over other communication forums. Team members are expected to prepare for the meeting by ensuring they're familiar with the proposal and related discussion. The meeting will not include diff --git a/docs/project/evolution.md b/docs/project/evolution.md index c7852d5e4021f..2a3e9ef360e51 100644 --- a/docs/project/evolution.md +++ b/docs/project/evolution.md @@ -37,51 +37,54 @@ guidelines for The process is: -1. [Draft the proposal](#draft-the-proposal) +1. [Draft the proposal](#draft-the-proposal) - 1. [(optional) Discuss the idea early](#optional-discuss-the-idea-early) - 2. [Make a proposal](#make-a-proposal) - 3. [(optional) Elicit early, high-level feedback on the proposal](#optional-elicit-early_high_level-feedback-on-the-proposal) + 1. [(optional) Discuss the idea early](#optional-discuss-the-idea-early) + 2. [Make a proposal](#make-a-proposal) + 3. [(optional) Elicit early, high-level feedback on the proposal](#optional-elicit-early_high_level-feedback-on-the-proposal) -2. [Solicit and address proposal feedback](#solicit-and-address-proposal-feedback) +2. [Solicit and address proposal feedback](#solicit-and-address-proposal-feedback) - 1. [Request comments](#request-comments) - 2. [Community and reviewing team comments on proposal](#community-and-reviewing-team-comments-on-proposal) - 3. [(optional) Pause for a major revision](#optional-pause-for-a-major-revision) - 4. [Request a review manager](#request-a-review-manager) + 1. [Request comments](#request-comments) + 2. [Community and reviewing team comments on proposal](#community-and-reviewing-team-comments-on-proposal) + 3. [(optional) Pause for a major revision](#optional-pause-for-a-major-revision) + 4. [Request a review manager](#request-a-review-manager) -3. [Reviewing team makes a proposal decision](#reviewing-team-makes-a-proposal-decision) +3. [Reviewing team makes a proposal decision](#reviewing-team-makes-a-proposal-decision) - 1. [Prepare the document for a proposal decision](#prepare-the-document-for-a-proposal-decision) - 2. [Ask the reviewing team for a proposal decision](#ask-the-reviewing-team-for-a-proposal-decision) - 3. [(optional) Use the meeting to make a proposal decision](#optional-use-the-meeting-to-make-a-proposal-decision) + 1. [Prepare the document for a proposal decision](#prepare-the-document-for-a-proposal-decision) + 2. [Ask the reviewing team for a proposal decision](#ask-the-reviewing-team-for-a-proposal-decision) + 3. [(optional) Use the meeting to make a proposal decision](#optional-use-the-meeting-to-make-a-proposal-decision) -4. [Finalize the proposal decision](#finalize-the-proposal-decision) +4. [Finalize the proposal decision](#finalize-the-proposal-decision) - 1. [Publish the proposal decision](#publish-the-proposal-decision) - 2. [Community comments on proposal decision](#community-comments-on-proposal-decision) - 3. [(optional) Rollback the decision](#optional-rollback-the-decision) - 4. [Execute on proposal decision](#execute-on-proposal-decision) + 1. [Publish the proposal decision](#publish-the-proposal-decision) + 2. [Community comments on proposal decision](#community-comments-on-proposal-decision) + 3. [(optional) Rollback the decision](#optional-rollback-the-decision) + 4. [Execute on proposal decision](#execute-on-proposal-decision) ## Coordination Tools We use several tools to coordinate changes to Carbon: +- **GitHub pull requests** contain the actual proposal. Resolved proposals will + be committed with the associated decision. +- **GitHub issues** track the proposal process and life cycle. These are only + used to track the process, and should not be used for discussion. All GitHub + pull requests, Google Docs, and Discourse Forum topics should be linked from + the issue for easy indexing. - **Discourse Forum** topics will be used for the early idea discussion, any deeper discussions, or more high-level and meta points. - **Discord Chat** can be used for quick and real-time chats and Q&A. - - If there are important technical points raised or addressed, they should get - summarized on a relevant Discourse Forum topic. -- **Google Docs** is used for writing and reviewing proposals. This facilitates - collaborative editing and easy commenting about wording issues. + - If there are important technical points raised or addressed, they should + get summarized on a relevant Discourse Forum topic. - **Google Hangouts Meet** will be used for VC meetings, typically for decisions. - - Meetings should typically be summarized on a relevant Discourse Forum topic. + - Meetings should typically be summarized on a relevant Discourse Forum + topic. - **Google Calendar** will be used to track team meeting and vacation times. -- **GitHub issues** track the proposal process and life cycle. These are only - used to track the process, and should not be used for discussion. All Google - Docs and Discourse Forum topics should be linked from the issue for easy - indexing. +- **Google Docs** may be used for early draft proposals. This facilitates + collaborative editing and easy commenting about wording issues. ## Governance structure @@ -241,8 +244,7 @@ efficient. #### Make a proposal -The first part of making a proposal is to write up a Google Doc explaining, -roughly in the following order: +Start by creating a markdown proposal covering (roughly in order): - **Problem**: Information about the problem the proposal is trying to solve. - **Background**: Background on the problem and information needed to understand @@ -253,17 +255,14 @@ roughly in the following order: considered and rejected. We use a -[template for proposals](https://docs.google.com/document/d/1sqEnIWWZKTrtMz2XgD7_RqvogwbI0tBQjAZIvOabQsw/template/preview) -to make it easier for readers to recognize the style and structure. If you -already have a non-templated Doc, create a Doc using the template and copy -content over (without the original formatting) so that things like the license -header are present. - -Also create -[the initial GitHub tracking issue](https://github.com/carbon-language/carbon-proposals/issues/new?template=proposal.md). -Don't worry about whether the proposal will go anywhere; issues are cheap. -GitHub issues are expected to be used as an index of different in-flight -proposals, and may be helpful when trying to find others with similar ideas. +[template for proposals](https://github.com/carbon-language/carbon-lang/blob/master/proposals/templates.md). +Please use this to include structure and license information. Follow the +instructions under "TODO: Initial proposal setup". + +Please always create the GitHub tracking issue early. Don't worry about whether +the proposal will go anywhere; issues are cheap. GitHub issues are expected to +be used as an index of different in-flight proposals, and may be helpful when +trying to find others with similar ideas. When writing a proposal, try to keep it brief and focused to maximize the community's engagement in it. Beyond the above structure, try to use @@ -271,6 +270,11 @@ community's engagement in it. Beyond the above structure, try to use or [BLUF]() writing style to help readers rapidly skim the material. +The proposal's pull request may include changes in the same repo. Please be +thoughtful about how much effort you invest this way: it can help illustrate the +intent of a proposal and avoid duplicating text in the proposal, but proposals +may also need to be rewritten substantially or be deferred/declined. + Where parts of a proposal may have several ways to address them, feel free to list options and mark them as "open questions". When describing an open question, it is a good idea to describe a proposed solution as well as other @@ -281,26 +285,41 @@ reviewing team. Where the proposal makes a decision between multiple options, move them to the "alternatives" section so that it's clear why a given choice was made. +##### Drafting using Google Docs + +You may optionally use the +[Google Docs template](https://docs.google.com/document/d/1sqEnIWWZKTrtMz2XgD7_RqvogwbI0tBQjAZIvOabQsw/template/preview) +for early proposal versions, which can be transferred to Markdown later. Using +Google Docs can especially help iterate on a propsal with multiple authors. + +This template includes things like license headers and standard formatting. If +you already have a non-templated Doc, please create a new Doc using the template +and copy content over (without original formatting). + +If you use Google Docs for drafting, be sure to still use a Markdown pull +request for the RFC. + ##### Actions - **Author**: - - Write the proposal using - [the template](https://docs.google.com/document/d/1sqEnIWWZKTrtMz2XgD7_RqvogwbI0tBQjAZIvOabQsw/template/preview). - - The template has additional items under "TODO: Initial proposal setup". - - Note that Google Doc and GitHub issue templates have the status set to - `WIP`. + - Write the proposal using + [the template](https://github.com/carbon-language/carbon-lang/blob/master/proposals/templates.md). + - The template has additional instructions under "TODO: Initial + proposal setup". + - Note that proposal and GitHub issue templates have the status set to + `WIP`. #### (optional) Elicit early, high-level feedback on the proposal Authors may continue to use the `Evolution > Ideas` forum topic to advertise the proposal and elicit early, high-level feedback. Community commenters should -favor the forum topic (vs Doc comments) for high-level discussion. +favor the forum topic (vs GitHub comments) for high-level discussion. ##### Actions - **Author**: Update (or create if needed) the `Evolution > Ideas` forum topic to advertise the proposal and elicit early, high-level feedback. - - Add the topic's link to the GitHub issue. + - Add the topic's link to the GitHub issue. - **Community**: Provide [constructive commentary](commenting_guidelines.md) for ideas when feedback is solicited. @@ -310,8 +329,8 @@ favor the forum topic (vs Doc comments) for high-level discussion. Once authors feel the proposal is in good shape for wider evaluation from the relevant reviewing team (the core team, at present), they begin the more formal -process of evaluation by creating an `Evolution > Proposal Reviews` forum topic -for technical review of the proposal. +process of evaluation by creating an `Evolution > RFCs` forum topic for +technical review of the proposal. The topic should start off with a brief summary of the proposal and any prior discussion, as well as links to prior discussion topics. @@ -319,11 +338,11 @@ discussion, as well as links to prior discussion topics. ##### Actions - **Author**: - - Set both the Google Doc status and GitHub issue status label to `RFC`. - - Create an `Evolution > RFC` forum topic. - - Summarize the discussion points, along with a link to the Google Doc and - GitHub issue. - - Add the topic's link to the GitHub issue. + - Set both the proposal status and GitHub issue status label to `RFC`. + - Create an `Evolution > RFCs` forum topic. + - Summarize the discussion points, along with a link to the pull + request and GitHub issue. + - Add the topic's link to the GitHub issue. #### Community and reviewing team comments on proposal @@ -346,8 +365,8 @@ also be added where the author isn't confident about the best approach. ##### Actions - **Author**: - - Update the Doc and/or comment in the topic to address feedback. - - Create GitHub issues for any open questions to be revisited later. + - Update the pull request and/or comment in the topic to address feedback. + - Create GitHub issues for any open questions to be revisited later. - **Reviewing team and community**: Provide [constructive commentary](commenting_guidelines.md) for proposals. @@ -367,9 +386,9 @@ discussion points thus far (with links to those prior topics). ##### Actions - **Author**: - - Announce to the Discourse Forum topic that the proposal is undergoing major - revision. - - Set both the Google Doc status and GitHub issue status label to `WIP`. + - Announce to the Discourse Forum topic that the proposal is undergoing + major revision. + - Set both the proposal status and GitHub issue status label to `WIP`. - **Reviewing team and community**: Refrain from commenting until the author solicits feedback again. @@ -392,36 +411,29 @@ the reviewing team will be asked to start making a decision after a day. ##### Actions - **Author**: - - Ensure all comments are resolved. - - Create a `Evolution > Review manager requests` topic asking for a review - manager, providing a link to the proposal's Doc and GitHub issue. - - Add the topic's link to the GitHub issue. + - Ensure all comments are resolved. + - Create a `Evolution > Review manager requests` topic asking for a review + manager, providing a link to the proposal's pull request and GitHub + issue. + - Add the topic's link to the GitHub issue. - **Review manager**: - - Ask reviewing team members to review the proposal when needed. - - Double-check that comment threads are addressed by the proposal. - - Update the `Evolution > RFC` topic with a last call for comments. + - 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 #### Prepare the document for a proposal decision Going into a decision, it's expected that no more significant changes will be -made. The review manager should ask the proposal author to transfer ownership of -the proposal's Doc to the review manager. The review manager should then change -all "edit" access to "comment". - -For the rest of the review, the review manager should reject all non-typo -suggestions to the proposal. Although the author should continue to respond to -reviewing team comments, if any significant changes need to be made, the -decision should be cancelled and the proposal should be returned to the author -for major revision. +made. The proposal author should stop making any non-typo edits to the text. Any +significant edit will be treated as a major revision, cancelling the decision +request. The author should still respond to review comments, just without +making/accepting edits. ##### Actions -- **Author**: - [Transfer ownership](https://support.google.com/docs/answer/2494892) of the - proposal's Doc to the review manager. -- **Review manager**: Change all edit access on the proposal to comment-only. +- **Author**: Stop making changes to the proposal. #### Ask the reviewing team for a proposal decision @@ -437,17 +449,17 @@ discussion. Try to respond to the Discourse Forum topic promptly with: - A position (either affirming or objecting) is strongly preferred, although standing aside is allowed. - - Rationales for positions should be based on discussion on the proposal's - `Evolution > RFC` topic, and providing links helps write the decision. + - 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. + - The reviewing team will participate in the proposal community comment + period, so that substantive feedback can be incorporated by the author + prior to requesting a decision. - A request to use the meeting for discussion. - - All topics for discussion will be captured either in the agenda or as a - comment on the Doc, to ensure they're ready for the meeting. + - 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. @@ -457,22 +469,22 @@ make decisions. ##### Actions - **Author**: - - Respond to comments. + - Respond to comments. - **Review manager:** - - Set both the Google Doc status and GitHub issue status label to - `needs decision`. - - In the Doc history, label the latest revision as `needs decision` - - Create an `Evolution > Proposal decisions` topic for pre-meeting discussion. - - Tentatively add the decision to the meeting one week in advance (or four - working days, if longer), and use that meeting if necessary to reach - consensus. - - Monitor the topic for a consensus decision. - - If a consensus is reached, ensure there's enough information to write a - decision. + - Set both the proposal status and GitHub issue status label to + `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. + - Review the proposal again and make comments if needed. + - Participate in reaching a consensus, or explicitly stand aside. + - Offer justifications towards a decision. #### (optional) Use the meeting to make a proposal decision @@ -491,13 +503,13 @@ 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. + - 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. + - Participate in reaching a consensus, or explicitly stand aside. + - Offer justifications towards a decision. ### Finalize the proposal decision @@ -517,24 +529,31 @@ author again. It's not necessary to switch ownership back. ##### Actions +- **Author**: + - If the proposal needs more changes: + - Set both the proposal status and GitHub issue status label to `WIP`. + - If the proposal is deferred or declined: + - Set both the proposal status and GitHub issue status label to + ``. + - Close the pull request, if appropriate. + - If the proposal is accepted: + - Set both the proposal status and GitHub issue status label to + `accepted`. + - When the proposal is approved by the reviewing team, commit it. + - Add a link to the committed version to the GitHub issue. - **Review manager**: - - If the proposal needs more changes: - - Grant the author edit access to the Doc again. - - Set both the Google Doc status and GitHub issue status label to `WIP`. - - If the proposal is done changing: - - Set both the Google Doc status and GitHub issue status label to - ``. - - In the Doc history, label the latest revision as ``. - - Write the - [formal decision](consensus_decision_making.md#formal-decision-content), - possibly with help from the reviewing team. - - (optional): Create a GitHub issue for issues that should be revisited in - the future. Link to these from the main GitHub issue. - - Create an `Evolution > Announcements` forum topic with the decision and a - summary of the rationale. - - Add the topic's link to the GitHub issue. -- **Reviewing team**: Help draft any rationale needed by the review manager for - the decision. + - Write the + [formal decision](consensus_decision_making.md#formal-decision-content), + possibly with help from the reviewing team. + - Formal decisions are stored at `/proposals/p####-decision.md`. + - (optional): Create a GitHub issue for issues that should be + revisited in the future. Link to these from the main GitHub issue. + - Create an `Evolution > Announcements` forum topic with the decision and a + summary of the rationale. + - Add the topic's link to the GitHub issue. +- **Reviewing team**: + - Approve the proposal. + - Help draft any rationale needed by the review manager for the decision. #### Community comments on proposal decision @@ -582,7 +601,8 @@ should be exceptional. ##### Actions -- **Author**: Roll back any dependent changes. +- **Author**: + - Roll back the committed proposal and any dependent changes. - **Reviewing team member**: State new, non-consensus position on `Evolution > Decisions` forum topic. - **Review manager**: Return to @@ -610,11 +630,11 @@ revisit the decision. ##### Actions - **Review manager**: - - Commit the proposal PDF to the GitHub decision repository. - - Once committed, add a link to the PDF in the GitHub issue. - - Move the Doc to the archive folder. - - Update the `Evolution > Announcements` forum topic with the final decision. - - Close the GitHub issue. + - Commit the proposal decision. + - Add a link to the committed version to the GitHub issue. + - Update the `Evolution > Announcements` forum topic with the final + decision. + - Close the GitHub issue. - **Author**: Start making dependent changes to apply the proposal. ## Acknowledgements From 068e69b8ed89b6ce3c1346b3048433093adcc451 Mon Sep 17 00:00:00 2001 From: jonmeow <46229924+jonmeow@users.noreply.github.com> Date: Wed, 13 May 2020 11:16:06 -0700 Subject: [PATCH 03/11] Text improvement --- proposals/p0001.md | 296 +++++++++++++++++++++++---------------------- 1 file changed, 151 insertions(+), 145 deletions(-) diff --git a/proposals/p0001.md b/proposals/p0001.md index 92ad90b1f7f77..acf4a2f6854b0 100644 --- a/proposals/p0001.md +++ b/proposals/p0001.md @@ -34,9 +34,9 @@ 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? + - What if there are multiple contributors to a proposal? - How easy is it to comment on a proposal? - - What about small typo fixes? + - 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? @@ -84,11 +84,11 @@ possible flows: 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. + - 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. + - 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. + - 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. @@ -118,103 +118,107 @@ Pros: 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. + - 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. + - 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). + - 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. + - 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. + - 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. + - 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. + - 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](https://docs.google.com/document/d/1pm_NgSVmitTAP4b784RV-wDe7wR-0Ml6l1qan0iWENw/edit#heading=h.l755sd9irx3w); - we'll probably want to recommend a specific extension to the community. + - [Extensions exist](https://docs.google.com/document/d/1pm_NgSVmitTAP4b784RV-wDe7wR-0Ml6l1qan0iWENw/edit#heading=h.l755sd9irx3w); + 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. + - 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. + - 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. + - 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 concerns. - - We've considered creating a GSuite domain for Carbon documentation to help - address this. However, it may not address everyone's concerns. + - 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 @@ -230,11 +234,11 @@ Cons: 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. + - 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. + - 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. @@ -245,62 +249,64 @@ If the proposal needs to be checked later to figure out why a decision was made: - 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. + - 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. + - 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. + - 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. + - 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. + - 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. + - 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. + - 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. + - 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 @@ -321,9 +327,9 @@ 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). + - _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 @@ -437,9 +443,9 @@ Pros: 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 while we're a small project. + - 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 while we're a small project. - Access controls are part of the parent repo, and so will be less restricted than if we had a separate proposals repo. @@ -486,35 +492,35 @@ comments together, as in a review. [Google Docs](https://support.google.com/docs/answer/65129?co=GENIE.Platform%3DDesktop&hl=en): -1. Follow the link to the doc -2. Select text to comment on -3. Click on "+" to add a comment (or use keyboard shortcut) -4. Enter text -5. Click "Comment" +1. Follow the link to the doc +2. Select text to comment on +3. Click on "+" to add a comment (or use keyboard shortcut) +4. Enter text +5. Click "Comment" [GitHub](https://help.github.com/en/enterprise/2.14/user/articles/commenting-on-a-pull-request): -1. Follow the link to a pull request -2. Click on "+" next to line to comment on -3. Enter text -4. Click "Add single comment" +1. Follow the link to a pull request +2. Click on "+" next to line to comment on +3. Enter text +4. Click "Add single comment" #### Suggesting edits [Google Docs](https://support.google.com/docs/answer/6033474?co=GENIE.Platform%3DDesktop&hl=en): -1. Follow the link to the doc -2. Select text to suggest edit on -3. Type suggested edit +1. Follow the link to the doc +2. Select text to suggest edit on +3. Type suggested edit [GitHub](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request): -1. Follow the link to a pull request -2. Click on "+" next to line to comment on -3. Optionally select multiple lines -4. Click on the left-most icon, a doc with a "+" on it -5. Edit quoted text -6. Click "Add single comment" +1. Follow the link to a pull request +2. Click on "+" next to line to comment on +3. Optionally select multiple lines +4. Click on the left-most icon, a doc with a "+" on it +5. Edit quoted text +6. Click "Add single comment" ### Google Docs add-ons @@ -604,7 +610,7 @@ 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. + - StackEdit docs aren't Google Docs, comments aren't Google Docs comments. ### GitHub Markdown syntax highlighting From 02fe735f2f5209efec3b2bd5d1ce686786a59b12 Mon Sep 17 00:00:00 2001 From: jonmeow <46229924+jonmeow@users.noreply.github.com> Date: Wed, 13 May 2020 12:12:25 -0700 Subject: [PATCH 04/11] Add file name to template. --- proposals/template.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/proposals/template.md b/proposals/template.md index 69cef4313f2b3..b372ecd210c90 100644 --- a/proposals/template.md +++ b/proposals/template.md @@ -8,11 +8,13 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 1. Create a GitHub tracking issue in this repo using [the template](https://github.com/carbon-language/carbon-lang/issues/new?template=proposal.md). -2. Prepare a pull request with the proposal, and add a link to it on the +2. Name this file `/proposals/p####.md`, where `####` should be the issue + number. +3. Prepare a pull request with the proposal, and add a link to it on the tracking issue. - - Although you may want to add more files to the pull request later, most - proposals will be very bare at this point. -3. Delete this section. + - Although you may want to add more files to the pull request later, most + proposals will be very bare at this point. +4. Delete this section. TODOs indicate where content should be updated for a proposal. See [Carbon Governance and Evolution](https://github.com/carbon-language/carbon-lang/blob/master/docs/project/evolution.md) From 5e336a6186df9bcad30f16a53eaf567c629cd5e1 Mon Sep 17 00:00:00 2001 From: jonmeow <46229924+jonmeow@users.noreply.github.com> Date: Thu, 14 May 2020 09:41:17 -0700 Subject: [PATCH 05/11] Re-pretty --- docs/project/consensus_decision_making.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/project/consensus_decision_making.md b/docs/project/consensus_decision_making.md index 10580a82f32aa..cb166dae63f37 100644 --- a/docs/project/consensus_decision_making.md +++ b/docs/project/consensus_decision_making.md @@ -56,15 +56,15 @@ 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. + - 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. + - 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 From 398b4d07c660fc7d7196f6cbc3b2873de7ce7b5b Mon Sep 17 00:00:00 2001 From: jonmeow <46229924+jonmeow@users.noreply.github.com> Date: Thu, 14 May 2020 09:45:19 -0700 Subject: [PATCH 06/11] Re-pretty --- proposals/p0001.md | 257 +++++++++++++++++++++--------------------- proposals/template.md | 4 +- 2 files changed, 128 insertions(+), 133 deletions(-) diff --git a/proposals/p0001.md b/proposals/p0001.md index acf4a2f6854b0..aa560bc6c31c4 100644 --- a/proposals/p0001.md +++ b/proposals/p0001.md @@ -34,9 +34,9 @@ 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? + - What if there are multiple contributors to a proposal? - How easy is it to comment on a proposal? - - What about small typo fixes? + - 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? @@ -84,11 +84,11 @@ possible flows: 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. + - 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. + - 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. + - 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. @@ -118,107 +118,104 @@ Pros: 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. + - 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. + - 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). + - 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. + - 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. + - 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. + - 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. + - 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](https://docs.google.com/document/d/1pm_NgSVmitTAP4b784RV-wDe7wR-0Ml6l1qan0iWENw/edit#heading=h.l755sd9irx3w); - we'll probably want to recommend a specific extension to the community. + - [Extensions exist](https://docs.google.com/document/d/1pm_NgSVmitTAP4b784RV-wDe7wR-0Ml6l1qan0iWENw/edit#heading=h.l755sd9irx3w); + 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. + - 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. + - 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. + - 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/) + - 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. + - 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 @@ -234,11 +231,11 @@ Cons: 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. + - 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. + - 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. @@ -249,64 +246,62 @@ If the proposal needs to be checked later to figure out why a decision was made: - 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. + - 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. + - 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. + - 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. + - 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. + - 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. + - 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. + - 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. + - 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 @@ -327,9 +322,9 @@ 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). + - _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 @@ -443,9 +438,9 @@ Pros: 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 while we're a small project. + - 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 while we're a small project. - Access controls are part of the parent repo, and so will be less restricted than if we had a separate proposals repo. @@ -610,7 +605,7 @@ 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. + - StackEdit docs aren't Google Docs, comments aren't Google Docs comments. ### GitHub Markdown syntax highlighting diff --git a/proposals/template.md b/proposals/template.md index b372ecd210c90..ab5e425053a3c 100644 --- a/proposals/template.md +++ b/proposals/template.md @@ -12,8 +12,8 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception number. 3. Prepare a pull request with the proposal, and add a link to it on the tracking issue. - - Although you may want to add more files to the pull request later, most - proposals will be very bare at this point. + - Although you may want to add more files to the pull request later, most + proposals will be very bare at this point. 4. Delete this section. TODOs indicate where content should be updated for a proposal. See From 9a1a5eb11aabb28f608cb03b86362947af75b4b6 Mon Sep 17 00:00:00 2001 From: jonmeow <46229924+jonmeow@users.noreply.github.com> Date: Thu, 14 May 2020 11:17:23 -0700 Subject: [PATCH 07/11] Prettier --- docs/project/commenting_guidelines.md | 13 +- docs/project/evolution.md | 191 +++++++++++++------------- 2 files changed, 99 insertions(+), 105 deletions(-) diff --git a/docs/project/commenting_guidelines.md b/docs/project/commenting_guidelines.md index e8feb47f56753..b221d36bbe462 100644 --- a/docs/project/commenting_guidelines.md +++ b/docs/project/commenting_guidelines.md @@ -17,19 +17,18 @@ always try to keep feedback, even when critical, constructive and supportive. 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. - **Use Discourse Forums for long comments.** GitHub is good for short-to-moderate-sized comments. Discourse Forums is better for long, detailed comments, particularly where multiple parties may get involved in discussion. - - Use the forum topic created by the author, rather than creating a new - topic. It needs to be easy for authors and other reviewers to find - comments. - - If your comment represents a significant change to the doc, include a - list of pros and cons. Even if the author disagrees with the change, they - can use those to document the alternative. + - Use the forum topic created by the author, rather than creating a new topic. + It needs to be easy for authors and other reviewers to find comments. + - If your comment represents a significant change to the doc, include a list + of pros and cons. Even if the author disagrees with the change, they can use + those to document the alternative. - **Be supportive in your criticism.** The author may be receiving many comments, and we want to keep contributors motivated to respond. diff --git a/docs/project/evolution.md b/docs/project/evolution.md index 2a3e9ef360e51..83ada917b2f49 100644 --- a/docs/project/evolution.md +++ b/docs/project/evolution.md @@ -39,29 +39,29 @@ The process is: 1. [Draft the proposal](#draft-the-proposal) - 1. [(optional) Discuss the idea early](#optional-discuss-the-idea-early) - 2. [Make a proposal](#make-a-proposal) - 3. [(optional) Elicit early, high-level feedback on the proposal](#optional-elicit-early_high_level-feedback-on-the-proposal) + 1. [(optional) Discuss the idea early](#optional-discuss-the-idea-early) + 2. [Make a proposal](#make-a-proposal) + 3. [(optional) Elicit early, high-level feedback on the proposal](#optional-elicit-early_high_level-feedback-on-the-proposal) 2. [Solicit and address proposal feedback](#solicit-and-address-proposal-feedback) - 1. [Request comments](#request-comments) - 2. [Community and reviewing team comments on proposal](#community-and-reviewing-team-comments-on-proposal) - 3. [(optional) Pause for a major revision](#optional-pause-for-a-major-revision) - 4. [Request a review manager](#request-a-review-manager) + 1. [Request comments](#request-comments) + 2. [Community and reviewing team comments on proposal](#community-and-reviewing-team-comments-on-proposal) + 3. [(optional) Pause for a major revision](#optional-pause-for-a-major-revision) + 4. [Request a review manager](#request-a-review-manager) 3. [Reviewing team makes a proposal decision](#reviewing-team-makes-a-proposal-decision) - 1. [Prepare the document for a proposal decision](#prepare-the-document-for-a-proposal-decision) - 2. [Ask the reviewing team for a proposal decision](#ask-the-reviewing-team-for-a-proposal-decision) - 3. [(optional) Use the meeting to make a proposal decision](#optional-use-the-meeting-to-make-a-proposal-decision) + 1. [Prepare the document for a proposal decision](#prepare-the-document-for-a-proposal-decision) + 2. [Ask the reviewing team for a proposal decision](#ask-the-reviewing-team-for-a-proposal-decision) + 3. [(optional) Use the meeting to make a proposal decision](#optional-use-the-meeting-to-make-a-proposal-decision) 4. [Finalize the proposal decision](#finalize-the-proposal-decision) - 1. [Publish the proposal decision](#publish-the-proposal-decision) - 2. [Community comments on proposal decision](#community-comments-on-proposal-decision) - 3. [(optional) Rollback the decision](#optional-rollback-the-decision) - 4. [Execute on proposal decision](#execute-on-proposal-decision) + 1. [Publish the proposal decision](#publish-the-proposal-decision) + 2. [Community comments on proposal decision](#community-comments-on-proposal-decision) + 3. [(optional) Rollback the decision](#optional-rollback-the-decision) + 4. [Execute on proposal decision](#execute-on-proposal-decision) ## Coordination Tools @@ -76,12 +76,11 @@ We use several tools to coordinate changes to Carbon: - **Discourse Forum** topics will be used for the early idea discussion, any deeper discussions, or more high-level and meta points. - **Discord Chat** can be used for quick and real-time chats and Q&A. - - If there are important technical points raised or addressed, they should - get summarized on a relevant Discourse Forum topic. + - If there are important technical points raised or addressed, they should get + summarized on a relevant Discourse Forum topic. - **Google Hangouts Meet** will be used for VC meetings, typically for decisions. - - Meetings should typically be summarized on a relevant Discourse Forum - topic. + - Meetings should typically be summarized on a relevant Discourse Forum topic. - **Google Calendar** will be used to track team meeting and vacation times. - **Google Docs** may be used for early draft proposals. This facilitates collaborative editing and easy commenting about wording issues. @@ -302,12 +301,12 @@ request for the RFC. ##### Actions - **Author**: - - Write the proposal using - [the template](https://github.com/carbon-language/carbon-lang/blob/master/proposals/templates.md). - - The template has additional instructions under "TODO: Initial - proposal setup". - - Note that proposal and GitHub issue templates have the status set to - `WIP`. + - Write the proposal using + [the template](https://github.com/carbon-language/carbon-lang/blob/master/proposals/templates.md). + - The template has additional instructions under "TODO: Initial proposal + setup". + - Note that proposal and GitHub issue templates have the status set to + `WIP`. #### (optional) Elicit early, high-level feedback on the proposal @@ -319,7 +318,7 @@ favor the forum topic (vs GitHub comments) for high-level discussion. - **Author**: Update (or create if needed) the `Evolution > Ideas` forum topic to advertise the proposal and elicit early, high-level feedback. - - Add the topic's link to the GitHub issue. + - Add the topic's link to the GitHub issue. - **Community**: Provide [constructive commentary](commenting_guidelines.md) for ideas when feedback is solicited. @@ -338,11 +337,11 @@ discussion, as well as links to prior discussion topics. ##### Actions - **Author**: - - Set both the proposal status and GitHub issue status label to `RFC`. - - Create an `Evolution > RFCs` forum topic. - - Summarize the discussion points, along with a link to the pull - request and GitHub issue. - - Add the topic's link to the GitHub issue. + - Set both the proposal status and GitHub issue status label to `RFC`. + - Create an `Evolution > RFCs` forum topic. + - Summarize the discussion points, along with a link to the pull request and + GitHub issue. + - Add the topic's link to the GitHub issue. #### Community and reviewing team comments on proposal @@ -365,8 +364,8 @@ also be added where the author isn't confident about the best approach. ##### Actions - **Author**: - - Update the pull request and/or comment in the topic to address feedback. - - Create GitHub issues for any open questions to be revisited later. + - Update the pull request and/or comment in the topic to address feedback. + - Create GitHub issues for any open questions to be revisited later. - **Reviewing team and community**: Provide [constructive commentary](commenting_guidelines.md) for proposals. @@ -386,9 +385,9 @@ discussion points thus far (with links to those prior topics). ##### Actions - **Author**: - - Announce to the Discourse Forum topic that the proposal is undergoing - major revision. - - Set both the proposal status and GitHub issue status label to `WIP`. + - Announce to the Discourse Forum topic that the proposal is undergoing major + revision. + - Set both the proposal status and GitHub issue status label to `WIP`. - **Reviewing team and community**: Refrain from commenting until the author solicits feedback again. @@ -411,15 +410,14 @@ the reviewing team will be asked to start making a decision after a day. ##### Actions - **Author**: - - Ensure all comments are resolved. - - Create a `Evolution > Review manager requests` topic asking for a review - manager, providing a link to the proposal's pull request and GitHub - issue. - - Add the topic's link to the GitHub issue. + - Ensure all comments are resolved. + - Create a `Evolution > Review manager requests` topic asking for a review + manager, providing a link to the proposal's pull request and GitHub issue. + - Add the topic's link to the GitHub issue. - **Review manager**: - - Ask reviewing team members to review the proposal when needed. - - Double-check that comment threads are addressed by the proposal. - - Update the `Evolution > RFCs` topic with a last call for comments. + - 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 @@ -449,17 +447,17 @@ discussion. Try to respond to the Discourse Forum topic promptly with: - A position (either affirming or objecting) is strongly preferred, although standing aside is allowed. - - Rationales for positions should be based on discussion on the proposal's - `Evolution > RFCs` topic, and providing links helps write the decision. + - 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. + - 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. + - 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. @@ -469,22 +467,21 @@ make decisions. ##### Actions - **Author**: - - Respond to comments. + - Respond to comments. - **Review manager:** - - Set both the proposal status and GitHub issue status label to - `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. + - Set both the proposal status and GitHub issue status label to + `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. + - 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 @@ -503,13 +500,13 @@ 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. + - 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. + - Participate in reaching a consensus, or explicitly stand aside. + - Offer justifications towards a decision. ### Finalize the proposal decision @@ -530,30 +527,29 @@ author again. It's not necessary to switch ownership back. ##### Actions - **Author**: - - If the proposal needs more changes: - - Set both the proposal status and GitHub issue status label to `WIP`. - - If the proposal is deferred or declined: - - Set both the proposal status and GitHub issue status label to - ``. - - Close the pull request, if appropriate. - - If the proposal is accepted: - - Set both the proposal status and GitHub issue status label to - `accepted`. - - When the proposal is approved by the reviewing team, commit it. - - Add a link to the committed version to the GitHub issue. + - If the proposal needs more changes: + - Set both the proposal status and GitHub issue status label to `WIP`. + - If the proposal is deferred or declined: + - Set both the proposal status and GitHub issue status label to + ``. + - Close the pull request, if appropriate. + - If the proposal is accepted: + - Set both the proposal status and GitHub issue status label to `accepted`. + - When the proposal is approved by the reviewing team, commit it. + - Add a link to the committed version to the GitHub issue. - **Review manager**: - - Write the - [formal decision](consensus_decision_making.md#formal-decision-content), - possibly with help from the reviewing team. - - Formal decisions are stored at `/proposals/p####-decision.md`. - - (optional): Create a GitHub issue for issues that should be - revisited in the future. Link to these from the main GitHub issue. - - Create an `Evolution > Announcements` forum topic with the decision and a - summary of the rationale. - - Add the topic's link to the GitHub issue. + - Write the + [formal decision](consensus_decision_making.md#formal-decision-content), + possibly with help from the reviewing team. + - Formal decisions are stored at `/proposals/p####-decision.md`. + - (optional): Create a GitHub issue for issues that should be revisited in + the future. Link to these from the main GitHub issue. + - Create an `Evolution > Announcements` forum topic with the decision and a + summary of the rationale. + - Add the topic's link to the GitHub issue. - **Reviewing team**: - - Approve the proposal. - - Help draft any rationale needed by the review manager for the decision. + - Approve the proposal. + - Help draft any rationale needed by the review manager for the decision. #### Community comments on proposal decision @@ -602,7 +598,7 @@ should be exceptional. ##### Actions - **Author**: - - Roll back the committed proposal and any dependent changes. + - Roll back the committed proposal and any dependent changes. - **Reviewing team member**: State new, non-consensus position on `Evolution > Decisions` forum topic. - **Review manager**: Return to @@ -630,11 +626,10 @@ revisit the decision. ##### Actions - **Review manager**: - - Commit the proposal decision. - - Add a link to the committed version to the GitHub issue. - - Update the `Evolution > Announcements` forum topic with the final - decision. - - Close the GitHub issue. + - Commit the proposal decision. + - Add a link to the committed version to the GitHub issue. + - Update the `Evolution > Announcements` forum topic with the final decision. + - Close the GitHub issue. - **Author**: Start making dependent changes to apply the proposal. ## Acknowledgements From a22b51245139d425e122d14688a8758034b86d1c Mon Sep 17 00:00:00 2001 From: Jon Meow <46229924+jonmeow@users.noreply.github.com> Date: Tue, 19 May 2020 15:19:09 -0700 Subject: [PATCH 08/11] Update docs/project/evolution.md Co-authored-by: Richard Smith --- docs/project/evolution.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/project/evolution.md b/docs/project/evolution.md index 83ada917b2f49..791f79d4a919d 100644 --- a/docs/project/evolution.md +++ b/docs/project/evolution.md @@ -254,7 +254,7 @@ Start by creating a markdown proposal covering (roughly in order): considered and rejected. We use a -[template for proposals](https://github.com/carbon-language/carbon-lang/blob/master/proposals/templates.md). +[template for proposals](https://github.com/carbon-language/carbon-lang/blob/master/proposals/template.md). Please use this to include structure and license information. Follow the instructions under "TODO: Initial proposal setup". From 584b7adc21a80b5023882d9f53a8676e60ea2543 Mon Sep 17 00:00:00 2001 From: Jon Meow <46229924+jonmeow@users.noreply.github.com> Date: Tue, 19 May 2020 15:20:08 -0700 Subject: [PATCH 09/11] Update proposals/template.md --- proposals/template.md | 1 - 1 file changed, 1 deletion(-) diff --git a/proposals/template.md b/proposals/template.md index ab5e425053a3c..948f2a9fe63a8 100644 --- a/proposals/template.md +++ b/proposals/template.md @@ -22,7 +22,6 @@ for more details. # Carbon: TODO -- **Authors:** TODO - **[Tracking issue](https://github.com/carbon-language/carbon-lang/issues/TODO)** - **Status:** RFC - **Created:** 2020-MM-DD (TODO) From 2ae7f36c15a72309fda2e2746bcd2ad1e78c38f1 Mon Sep 17 00:00:00 2001 From: jonmeow <46229924+jonmeow@users.noreply.github.com> Date: Tue, 2 Jun 2020 10:51:40 -0700 Subject: [PATCH 10/11] Reducing to just the proposal --- docs/project/evolution.md | 181 +++++++++++++++++--------------------- proposals/README.md | 4 - proposals/template.md | 52 ----------- 3 files changed, 83 insertions(+), 154 deletions(-) delete mode 100644 proposals/README.md delete mode 100644 proposals/template.md diff --git a/docs/project/evolution.md b/docs/project/evolution.md index 791f79d4a919d..1581c8e7d3c90 100644 --- a/docs/project/evolution.md +++ b/docs/project/evolution.md @@ -1,11 +1,11 @@ +# Carbon: Governance and Evolution + -# Carbon: Governance and Evolution - The Carbon project aims to provide consistent and clear governance and language evolution over time. We want to provide a reasonably broad representation for the community contributing to Carbon, including their diverse backgrounds and @@ -37,53 +37,51 @@ guidelines for The process is: -1. [Draft the proposal](#draft-the-proposal) +1. [Draft the proposal](#draft-the-proposal) - 1. [(optional) Discuss the idea early](#optional-discuss-the-idea-early) - 2. [Make a proposal](#make-a-proposal) - 3. [(optional) Elicit early, high-level feedback on the proposal](#optional-elicit-early_high_level-feedback-on-the-proposal) + 1. [(optional) Discuss the idea early](#optional-discuss-the-idea-early) + 2. [Make a proposal](#make-a-proposal) + 3. [(optional) Elicit early, high-level feedback on the proposal](#optional-elicit-early_high_level-feedback-on-the-proposal) -2. [Solicit and address proposal feedback](#solicit-and-address-proposal-feedback) +2. [Solicit and address proposal feedback](#solicit-and-address-proposal-feedback) - 1. [Request comments](#request-comments) - 2. [Community and reviewing team comments on proposal](#community-and-reviewing-team-comments-on-proposal) - 3. [(optional) Pause for a major revision](#optional-pause-for-a-major-revision) - 4. [Request a review manager](#request-a-review-manager) + 1. [Request comments](#request-comments) + 2. [Community and reviewing team comments on proposal](#community-and-reviewing-team-comments-on-proposal) + 3. [(optional) Pause for a major revision](#optional-pause-for-a-major-revision) + 4. [Request a review manager](#request-a-review-manager) -3. [Reviewing team makes a proposal decision](#reviewing-team-makes-a-proposal-decision) +3. [Reviewing team makes a proposal decision](#reviewing-team-makes-a-proposal-decision) - 1. [Prepare the document for a proposal decision](#prepare-the-document-for-a-proposal-decision) - 2. [Ask the reviewing team for a proposal decision](#ask-the-reviewing-team-for-a-proposal-decision) - 3. [(optional) Use the meeting to make a proposal decision](#optional-use-the-meeting-to-make-a-proposal-decision) + 1. [Prepare the document for a proposal decision](#prepare-the-document-for-a-proposal-decision) + 2. [Ask the reviewing team for a proposal decision](#ask-the-reviewing-team-for-a-proposal-decision) + 3. [(optional) Use the meeting to make a proposal decision](#optional-use-the-meeting-to-make-a-proposal-decision) -4. [Finalize the proposal decision](#finalize-the-proposal-decision) +4. [Finalize the proposal decision](#finalize-the-proposal-decision) - 1. [Publish the proposal decision](#publish-the-proposal-decision) - 2. [Community comments on proposal decision](#community-comments-on-proposal-decision) - 3. [(optional) Rollback the decision](#optional-rollback-the-decision) - 4. [Execute on proposal decision](#execute-on-proposal-decision) + 1. [Publish the proposal decision](#publish-the-proposal-decision) + 2. [Community comments on proposal decision](#community-comments-on-proposal-decision) + 3. [(optional) Rollback the decision](#optional-rollback-the-decision) + 4. [Execute on proposal decision](#execute-on-proposal-decision) ## Coordination Tools We use several tools to coordinate changes to Carbon: -- **GitHub pull requests** contain the actual proposal. Resolved proposals will - be committed with the associated decision. -- **GitHub issues** track the proposal process and life cycle. These are only - used to track the process, and should not be used for discussion. All GitHub - pull requests, Google Docs, and Discourse Forum topics should be linked from - the issue for easy indexing. - **Discourse Forum** topics will be used for the early idea discussion, any deeper discussions, or more high-level and meta points. - **Discord Chat** can be used for quick and real-time chats and Q&A. - If there are important technical points raised or addressed, they should get summarized on a relevant Discourse Forum topic. +- **Google Docs** is used for writing and reviewing proposals. This facilitates + collaborative editing and easy commenting about wording issues. - **Google Hangouts Meet** will be used for VC meetings, typically for decisions. - Meetings should typically be summarized on a relevant Discourse Forum topic. - **Google Calendar** will be used to track team meeting and vacation times. -- **Google Docs** may be used for early draft proposals. This facilitates - collaborative editing and easy commenting about wording issues. +- **GitHub issues** track the proposal process and life cycle. These are only + used to track the process, and should not be used for discussion. All Google + Docs and Discourse Forum topics should be linked from the issue for easy + indexing. ## Governance structure @@ -243,7 +241,8 @@ efficient. #### Make a proposal -Start by creating a markdown proposal covering (roughly in order): +The first part of making a proposal is to write up a Google Doc explaining, +roughly in the following order: - **Problem**: Information about the problem the proposal is trying to solve. - **Background**: Background on the problem and information needed to understand @@ -254,14 +253,17 @@ Start by creating a markdown proposal covering (roughly in order): considered and rejected. We use a -[template for proposals](https://github.com/carbon-language/carbon-lang/blob/master/proposals/template.md). -Please use this to include structure and license information. Follow the -instructions under "TODO: Initial proposal setup". - -Please always create the GitHub tracking issue early. Don't worry about whether -the proposal will go anywhere; issues are cheap. GitHub issues are expected to -be used as an index of different in-flight proposals, and may be helpful when -trying to find others with similar ideas. +[template for proposals](https://docs.google.com/document/d/1sqEnIWWZKTrtMz2XgD7_RqvogwbI0tBQjAZIvOabQsw/template/preview) +to make it easier for readers to recognize the style and structure. If you +already have a non-templated Doc, create a Doc using the template and copy +content over (without the original formatting) so that things like the license +header are present. + +Also create +[the initial GitHub tracking issue](https://github.com/carbon-language/carbon-proposals/issues/new?template=proposal.md). +Don't worry about whether the proposal will go anywhere; issues are cheap. +GitHub issues are expected to be used as an index of different in-flight +proposals, and may be helpful when trying to find others with similar ideas. When writing a proposal, try to keep it brief and focused to maximize the community's engagement in it. Beyond the above structure, try to use @@ -269,11 +271,6 @@ community's engagement in it. Beyond the above structure, try to use or [BLUF]() writing style to help readers rapidly skim the material. -The proposal's pull request may include changes in the same repo. Please be -thoughtful about how much effort you invest this way: it can help illustrate the -intent of a proposal and avoid duplicating text in the proposal, but proposals -may also need to be rewritten substantially or be deferred/declined. - Where parts of a proposal may have several ways to address them, feel free to list options and mark them as "open questions". When describing an open question, it is a good idea to describe a proposed solution as well as other @@ -284,35 +281,20 @@ reviewing team. Where the proposal makes a decision between multiple options, move them to the "alternatives" section so that it's clear why a given choice was made. -##### Drafting using Google Docs - -You may optionally use the -[Google Docs template](https://docs.google.com/document/d/1sqEnIWWZKTrtMz2XgD7_RqvogwbI0tBQjAZIvOabQsw/template/preview) -for early proposal versions, which can be transferred to Markdown later. Using -Google Docs can especially help iterate on a propsal with multiple authors. - -This template includes things like license headers and standard formatting. If -you already have a non-templated Doc, please create a new Doc using the template -and copy content over (without original formatting). - -If you use Google Docs for drafting, be sure to still use a Markdown pull -request for the RFC. - ##### Actions - **Author**: - Write the proposal using - [the template](https://github.com/carbon-language/carbon-lang/blob/master/proposals/templates.md). - - The template has additional instructions under "TODO: Initial proposal - setup". - - Note that proposal and GitHub issue templates have the status set to + [the template](https://docs.google.com/document/d/1sqEnIWWZKTrtMz2XgD7_RqvogwbI0tBQjAZIvOabQsw/template/preview). + - The template has additional items under "TODO: Initial proposal setup". + - Note that Google Doc and GitHub issue templates have the status set to `WIP`. #### (optional) Elicit early, high-level feedback on the proposal Authors may continue to use the `Evolution > Ideas` forum topic to advertise the proposal and elicit early, high-level feedback. Community commenters should -favor the forum topic (vs GitHub comments) for high-level discussion. +favor the forum topic (vs Doc comments) for high-level discussion. ##### Actions @@ -328,8 +310,8 @@ favor the forum topic (vs GitHub comments) for high-level discussion. Once authors feel the proposal is in good shape for wider evaluation from the relevant reviewing team (the core team, at present), they begin the more formal -process of evaluation by creating an `Evolution > RFCs` forum topic for -technical review of the proposal. +process of evaluation by creating an `Evolution > Proposal Reviews` forum topic +for technical review of the proposal. The topic should start off with a brief summary of the proposal and any prior discussion, as well as links to prior discussion topics. @@ -337,9 +319,9 @@ discussion, as well as links to prior discussion topics. ##### Actions - **Author**: - - Set both the proposal status and GitHub issue status label to `RFC`. - - Create an `Evolution > RFCs` forum topic. - - Summarize the discussion points, along with a link to the pull request and + - Set both the Google Doc status and GitHub issue status label to `RFC`. + - Create an `Evolution > RFC` forum topic. + - Summarize the discussion points, along with a link to the Google Doc and GitHub issue. - Add the topic's link to the GitHub issue. @@ -364,7 +346,7 @@ also be added where the author isn't confident about the best approach. ##### Actions - **Author**: - - Update the pull request and/or comment in the topic to address feedback. + - Update the Doc and/or comment in the topic to address feedback. - Create GitHub issues for any open questions to be revisited later. - **Reviewing team and community**: Provide [constructive commentary](commenting_guidelines.md) for proposals. @@ -387,7 +369,7 @@ discussion points thus far (with links to those prior topics). - **Author**: - Announce to the Discourse Forum topic that the proposal is undergoing major revision. - - Set both the proposal status and GitHub issue status label to `WIP`. + - Set both the Google Doc status and GitHub issue status label to `WIP`. - **Reviewing team and community**: Refrain from commenting until the author solicits feedback again. @@ -412,26 +394,34 @@ the reviewing team will be asked to start making a decision after a day. - **Author**: - Ensure all comments are resolved. - Create a `Evolution > Review manager requests` topic asking for a review - manager, providing a link to the proposal's pull request and GitHub issue. + manager, providing a link to the proposal's Doc and GitHub issue. - Add the topic's link to the GitHub issue. - **Review manager**: - Ask reviewing team members to review the proposal when needed. - Double-check that comment threads are addressed by the proposal. - - Update the `Evolution > RFCs` topic with a last call for comments. + - Update the `Evolution > RFC` topic with a last call for comments. ### Reviewing team makes a proposal decision #### Prepare the document for a proposal decision Going into a decision, it's expected that no more significant changes will be -made. The proposal author should stop making any non-typo edits to the text. Any -significant edit will be treated as a major revision, cancelling the decision -request. The author should still respond to review comments, just without -making/accepting edits. +made. The review manager should ask the proposal author to transfer ownership of +the proposal's Doc to the review manager. The review manager should then change +all "edit" access to "comment". + +For the rest of the review, the review manager should reject all non-typo +suggestions to the proposal. Although the author should continue to respond to +reviewing team comments, if any significant changes need to be made, the +decision should be cancelled and the proposal should be returned to the author +for major revision. ##### Actions -- **Author**: Stop making changes to the proposal. +- **Author**: + [Transfer ownership](https://support.google.com/docs/answer/2494892) of the + proposal's Doc to the review manager. +- **Review manager**: Change all edit access on the proposal to comment-only. #### Ask the reviewing team for a proposal decision @@ -448,7 +438,7 @@ discussion. Try to respond to the Discourse Forum topic promptly with: - A position (either affirming or objecting) is strongly preferred, although standing aside is allowed. - Rationales for positions should be based on discussion on the proposal's - `Evolution > RFCs` topic, and providing links helps write the decision. + `Evolution > RFC` topic, and providing links helps write the decision. - A request for more time to review materials, to make it clear the intent is to participate in the decision. - Discussion regarding positions or the decision itself. @@ -457,7 +447,7 @@ discussion. Try to respond to the Discourse Forum topic promptly with: to requesting a decision. - A request to use the meeting for discussion. - All topics for discussion will be captured either in the agenda or as a - comment on the pull request, to ensure they're ready for the meeting. + comment on the Doc, to ensure they're ready for the meeting. The review manager should monitor the forum topic for consensus. If a decision is made before the meeting, the item should be removed from the meeting agenda. @@ -469,8 +459,9 @@ make decisions. - **Author**: - Respond to comments. - **Review manager:** - - Set both the proposal status and GitHub issue status label to + - Set both the Google Doc status and GitHub issue status label to `needs decision`. + - In the Doc history, label the latest revision as `needs decision` - Create an `Evolution > Proposal decisions` topic for pre-meeting discussion. - Tentatively add the decision to the meeting one week in advance (or four working days, if longer), and use that meeting if necessary to reach @@ -526,30 +517,24 @@ author again. It's not necessary to switch ownership back. ##### Actions -- **Author**: +- **Review manager**: - If the proposal needs more changes: - - Set both the proposal status and GitHub issue status label to `WIP`. - - If the proposal is deferred or declined: - - Set both the proposal status and GitHub issue status label to + - Grant the author edit access to the Doc again. + - Set both the Google Doc status and GitHub issue status label to `WIP`. + - If the proposal is done changing: + - Set both the Google Doc status and GitHub issue status label to ``. - - Close the pull request, if appropriate. - - If the proposal is accepted: - - Set both the proposal status and GitHub issue status label to `accepted`. - - When the proposal is approved by the reviewing team, commit it. - - Add a link to the committed version to the GitHub issue. -- **Review manager**: + - In the Doc history, label the latest revision as ``. - Write the [formal decision](consensus_decision_making.md#formal-decision-content), possibly with help from the reviewing team. - - Formal decisions are stored at `/proposals/p####-decision.md`. - (optional): Create a GitHub issue for issues that should be revisited in the future. Link to these from the main GitHub issue. - Create an `Evolution > Announcements` forum topic with the decision and a summary of the rationale. - Add the topic's link to the GitHub issue. -- **Reviewing team**: - - Approve the proposal. - - Help draft any rationale needed by the review manager for the decision. +- **Reviewing team**: Help draft any rationale needed by the review manager for + the decision. #### Community comments on proposal decision @@ -597,8 +582,7 @@ should be exceptional. ##### Actions -- **Author**: - - Roll back the committed proposal and any dependent changes. +- **Author**: Roll back any dependent changes. - **Reviewing team member**: State new, non-consensus position on `Evolution > Decisions` forum topic. - **Review manager**: Return to @@ -626,8 +610,9 @@ revisit the decision. ##### Actions - **Review manager**: - - Commit the proposal decision. - - Add a link to the committed version to the GitHub issue. + - Commit the proposal PDF to the GitHub decision repository. + - Once committed, add a link to the PDF in the GitHub issue. + - Move the Doc to the archive folder. - Update the `Evolution > Announcements` forum topic with the final decision. - Close the GitHub issue. - **Author**: Start making dependent changes to apply the proposal. diff --git a/proposals/README.md b/proposals/README.md deleted file mode 100644 index df21aab11459b..0000000000000 --- a/proposals/README.md +++ /dev/null @@ -1,4 +0,0 @@ -This directory contains all proposals for the carbon-lang repo. Files will be -named `p####.md`, where `####` is the corresponding tracking issue. They may -have associated subdirectories named `p####` which contain related files (e.g., -images) for the proposal. diff --git a/proposals/template.md b/proposals/template.md deleted file mode 100644 index 948f2a9fe63a8..0000000000000 --- a/proposals/template.md +++ /dev/null @@ -1,52 +0,0 @@ - - -# TODO: Initial proposal setup - -1. Create a GitHub tracking issue in this repo using - [the template](https://github.com/carbon-language/carbon-lang/issues/new?template=proposal.md). -2. Name this file `/proposals/p####.md`, where `####` should be the issue - number. -3. Prepare a pull request with the proposal, and add a link to it on the - tracking issue. - - Although you may want to add more files to the pull request later, most - proposals will be very bare at this point. -4. Delete this section. - -TODOs indicate where content should be updated for a proposal. See -[Carbon Governance and Evolution](https://github.com/carbon-language/carbon-lang/blob/master/docs/project/evolution.md) -for more details. - -# Carbon: TODO - -- **[Tracking issue](https://github.com/carbon-language/carbon-lang/issues/TODO)** -- **Status:** RFC -- **Created:** 2020-MM-DD (TODO) - -**_PLEASE_ DO NOT SHARE OUTSIDE CARBON FORUMS** - -## Problem - -TODO: What problem are you trying to solve? How important is that problem? Who -is impacted by it? - -## Background - -TODO: Is there any background that readers should consider to fully understand -this problem and your approach to solving it? - -## Proposal - -TODO: Briefly and at a high level, how do you propose to solve the problem? Why -will that in fact solve it? - -## Details - -TODO: Fully explain the details of the proposed solution. - -## Alternatives considered - -TODO: What alternative solutions have you considered? From 35a638435a84402ff17e8af3ec3eda4e4b4bb0c1 Mon Sep 17 00:00:00 2001 From: jonmeow <46229924+jonmeow@users.noreply.github.com> Date: Tue, 2 Jun 2020 10:52:59 -0700 Subject: [PATCH 11/11] Reducing PR --- docs/project/commenting_guidelines.md | 16 ++++++++-------- docs/project/consensus_decision_making.md | 14 +++++++------- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/project/commenting_guidelines.md b/docs/project/commenting_guidelines.md index b221d36bbe462..710289ba3d591 100644 --- a/docs/project/commenting_guidelines.md +++ b/docs/project/commenting_guidelines.md @@ -1,11 +1,11 @@ +# Carbon: Commenting guidelines + -# Carbon: Commenting guidelines - These commenting guidelines are complementary to the [evolution process](evolution.md). The community comments on proposals when the proposal's status is "RFC", providing both positive and critical feedback. We @@ -19,10 +19,10 @@ always try to keep feedback, even when critical, constructive and supportive. - Objections to specific phrasing should suggest alternative phrasing. -- **Use Discourse Forums for long comments.** GitHub is good for - short-to-moderate-sized comments. Discourse Forums is better for long, - detailed comments, particularly where multiple parties may get involved in - discussion. +- **Use Discourse Forums for long comments.** If a Google Doc comment would be + over two paragraphs, take it to the Discourse Forum topic. Doc comments are + good for quick, short feedback; detailed feedback is better shared on + Discourse Forums. - Use the forum topic created by the author, rather than creating a new topic. It needs to be easy for authors and other reviewers to find comments. diff --git a/docs/project/consensus_decision_making.md b/docs/project/consensus_decision_making.md index cb166dae63f37..20551f1315006 100644 --- a/docs/project/consensus_decision_making.md +++ b/docs/project/consensus_decision_making.md @@ -1,11 +1,11 @@ +# Carbon: Consensus decision-making + -# Carbon: Consensus decision-making - Carbon's teams will use a [blocking consensus decision-making process](https://en.wikipedia.org/wiki/Consensus_decision-making#Blocking) to make decisions on proposals. We want all voices to be heard; we expect to @@ -103,9 +103,9 @@ items, meetings will not be held. Agenda items (e.g., proposals) should be added at least one week in advance (or four working days, if longer), so that members have time to review items added to the agenda. Sub-items (e.g., proposal discussion points) should be added at -least one day before the meeting; every open GitHub pull request comment is -implicitly a sub-item. Please feel free to add items to the agenda and remove -them later if the agenda item is resolved over other communication forums. +least one day before the meeting; every open Google Doc comment is implicitly a +sub-item. Please feel free to add items to the agenda and remove them later if +the agenda item is resolved over other communication forums. Team members are expected to prepare for the meeting by ensuring they're familiar with the proposal and related discussion. The meeting will not include