diff --git a/docs/design/code_and_name_organization/README.md b/docs/design/code_and_name_organization/README.md index b263e7202503..14a7eaf030c2 100644 --- a/docs/design/code_and_name_organization/README.md +++ b/docs/design/code_and_name_organization/README.md @@ -49,7 +49,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception - [Referring to the package as `package`](#referring-to-the-package-as-package) - [Remove the `library` keyword from `package` and `import`](#remove-the-library-keyword-from-package-and-import) - [Rename package concept](#rename-package-concept) - - [No association between the filesystem path and library/namespace](#no-association-between-the-filesystem-path-and-librarynamespace) + - [No association between the file system path and library/namespace](#no-association-between-the-file-system-path-and-librarynamespace) - [Libraries](#libraries-1) - [Allow exporting namespaces](#allow-exporting-namespaces) - [Allow importing implementation files from within the same library](#allow-importing-implementation-files-from-within-the-same-library) @@ -765,7 +765,7 @@ These choices are made to assist human readability and tooling: tooling to determine what to expect. - Repeating the type in the filename makes it possible to check the type without reading file content. -- Repeating the type in the file content makes non-filesystem-based builds +- Repeating the type in the file content makes non-file-system-based builds possible. ## Open questions @@ -1020,7 +1020,7 @@ Disadvantages: - [Swift](https://developer.apple.com/documentation/swift_packages), as a distributable unit. -#### No association between the filesystem path and library/namespace +#### No association between the file system path and library/namespace Several languages create a strict association between the method for pulling in an API and the path to the file that provides it. For example: @@ -1028,10 +1028,10 @@ an API and the path to the file that provides it. For example: - In C++, `#include` refers to specific files without any abstraction. - For example, `#include "PATH/TO/FILE.h"` means there's a file `PATH/TO/FILE.h`. -- In Java, `package` and `import` both reflect filesystem structure. +- In Java, `package` and `import` both reflect file system structure. - For example, `import PATH.TO.FILE;` means there's a file `PATH/TO/FILE.java`. -- In Python, `import` requires matching filesystem structure. +- In Python, `import` requires matching file system structure. - For example, `import PATH.TO.FILE` means there's a file `PATH/TO/FILE.py`. - In TypeScript, `import` refers to specific files. @@ -1053,7 +1053,7 @@ Advantages: - The strict association makes it harder to move names between files without updating callers. - If there were a strict association of paths, it would also need to handle - filesystem-dependent casing behaviors. + file system dependent casing behaviors. - For example, on Windows, `project.carbon` and `Project.carbon` are conflicting filenames. This is exacerbated by paths, wherein a file `config` and a directory `Config/` would conflict, even though this @@ -1061,15 +1061,15 @@ Advantages: Disadvantages: -- A strict association between filesystem path and import path makes it easier - to find source files. This is used by some languages for compilation. +- A strict association between file system path and import path makes it + easier to find source files. This is used by some languages for compilation. - Allows getting rid of the `package` keyword by inferring related information - from the filesystem path. + from the file system path. -We are choosing to have some association between the filesystem path and library -for API files to make it easier to find a library's files. We are not getting -rid of the `package` keyword because we don't want to become dependent on -filesystem structures, particularly as it would increase the complexity of +We are choosing to have some association between the file system path and +library for API files to make it easier to find a library's files. We are not +getting rid of the `package` keyword because we don't want to become dependent +on file system structures, particularly as it would increase the complexity of distributed builds. ### Libraries @@ -1190,14 +1190,14 @@ Advantages: - Clearer distinction between the package and library, increasing readability. - We have chosen not to - [enforce filesystem paths](#strict-association-between-the-filesystem-path-and-librarynamespace) + [enforce file system paths](#strict-association-between-the-file-system-path-and-librarynamespace) in order to ease refactoring, and encouraging a mental model where they may match could confuse users. Disadvantages: - Uses multiple separators, so people need to type different characters. -- There is a preference for thinking of libraries like filesystem paths, even +- There is a preference for thinking of libraries like file system paths, even if they don't actually correspond. People like `/`, so we're going with `/`. diff --git a/docs/design/name_lookup.md b/docs/design/name_lookup.md index ef39f1db7379..8ca5beff8ebf 100644 --- a/docs/design/name_lookup.md +++ b/docs/design/name_lookup.md @@ -67,7 +67,7 @@ reference. #### Alternatives This implies that other names within your own package but not declared within -the file must be found via the package name. It isn't clear if this is the +the file must be found by way of the package name. It isn't clear if this is the desirable end state. We need to consider alternatives where names from the same library or any library in the same package are made immediately visible within the package scope for unqualified name lookup. diff --git a/docs/design/primitive_types.md b/docs/design/primitive_types.md index e59af2b07dab..0c57f9d3b765 100644 --- a/docs/design/primitive_types.md +++ b/docs/design/primitive_types.md @@ -87,7 +87,7 @@ the need to import things gratuitously. ### String view vs owning string -The right model of a string view vs. an owning string is still very much +The right model of a string view versus an owning string is still very much unsettled. ### Syntax for wrapping operations diff --git a/docs/design/structs.md b/docs/design/structs.md index d120b341e7d7..e8c3299468e5 100644 --- a/docs/design/structs.md +++ b/docs/design/structs.md @@ -77,7 +77,7 @@ constraints. The type itself is a compile-time constant value. All name access is done with the `.` notation. Constant members (including member types and member functions -which do not need an implicit object parameter) can be accessed via that +which do not need an implicit object parameter) can be accessed by way of that constant: `AdvancedWidget.NestedType`. Other members and member functions needing an object parameter (or "methods") must be accessed from an object of the type. @@ -99,8 +99,8 @@ special `Self` type. It may be interesting to consider separating the `self` syntax from the rest of the parameter pattern as it doesn't seem necessary to inject all of the special -rules (covariance vs. contravariance, special pointer handling) for `self` into -the general pattern matching system. +rules (covariance versus contravariance, special pointer handling) for `self` +into the general pattern matching system. ### Default access control level diff --git a/docs/design/syntactic_conventions.md b/docs/design/syntactic_conventions.md index 4d250147007f..0dae575207de 100644 --- a/docs/design/syntactic_conventions.md +++ b/docs/design/syntactic_conventions.md @@ -65,11 +65,11 @@ like something that people will get used to with time, it may be worthwhile to do some user research to understand the likely reaction distribution, strength of reaction, and any quantifiable impact these options have on measured readability. We have only found one _very_ weak source of research that focused -on the _order_ question (rather than type inference vs. explicit types or other -questions in this space). That was a very limited PhD student's study of Java -programmers that seemed to indicate improved latency for recalling the type of a -given variable name with types on the left (as in C++). However, those results -are _far_ from conclusive. +on the _order_ question (rather than type inference versus explicit types or +other questions in this space). That was a very limited PhD student's study of +Java programmers that seemed to indicate improved latency for recalling the type +of a given variable name with types on the left (as in C++). However, those +results are _far_ from conclusive. **TODO**: Get a useful link to this PhD research (a few of us got a copy from the professor directly). diff --git a/docs/project/commenting_guidelines.md b/docs/project/commenting_guidelines.md index 0737a25e871f..c946aa858a5a 100644 --- a/docs/project/commenting_guidelines.md +++ b/docs/project/commenting_guidelines.md @@ -24,8 +24,8 @@ always try to keep feedback, even when critical, constructive and supportive. keep the discussion focused in one place: the GitHub pull request. - If your comment represents a significant change to the proposal, include - a list of pros and cons. Even if the author disagrees with the change, - they can use those to document the alternative. + a list of advantages and disadvantages. Even if the author disagrees + with the change, they can use those to document the alternative. - Feel free to extract long side discussions to a Discourse Forum topic, but make sure any important conclusions or outcomes are reflected in either the GitHub comments or the change itself. diff --git a/docs/project/consensus_decision_making.md b/docs/project/consensus_decision_making.md index 274ae6f0c599..bfe5545e7c86 100644 --- a/docs/project/consensus_decision_making.md +++ b/docs/project/consensus_decision_making.md @@ -91,9 +91,10 @@ weekly meeting slot, which observers may attend. Members are expected to do their best to keep the slot available. Meetings will be held using Google Hangouts Meet. -Each time a team needs to make a decision, e.g., about a change to Carbon, it is -expected that we'll try to make a decision without using a live meeting. We will -only hold meetings when decisions cannot be resolved before the meeting. +Each time a team needs to make a decision, for example, about a change to +Carbon, it is expected that we'll try to make a decision without using a live +meeting. We will only hold meetings when decisions cannot be resolved before the +meeting. ### Agenda diff --git a/docs/project/contribution_tools.md b/docs/project/contribution_tools.md index 2a002fd95628..376297cba48f 100644 --- a/docs/project/contribution_tools.md +++ b/docs/project/contribution_tools.md @@ -74,7 +74,7 @@ To set up pre-commit, see the ```bash pip install pre-commit -# From within each carbon-language git repo: +# From within each carbon-language git repository: pre-commit install ``` @@ -111,7 +111,7 @@ PR and proposal file for a new proposal. It's documented in is a helper for scanning comments in GitHub. It's particularly intended to help find threads which need to be resolved. -Flags can be seen with `-h`. A couple key flags to be aware of are: +Options can be seen with `-h`. A couple key options to be aware of are: - `--long`: Prints long output, with the full comment. - `--comments-after LOGIN`: Only print threads where the final comment is not @@ -143,7 +143,7 @@ brew install github/gh/gh #### GitHub Desktop [GitHub Desktop](https://desktop.github.com/) provides a UI for managing git -repos. See the page for installation instructions. +repositories. See the page for installation instructions. ### Vim diff --git a/docs/project/evolution.md b/docs/project/evolution.md index 4cd02a345b6e..cec00271a12a 100644 --- a/docs/project/evolution.md +++ b/docs/project/evolution.md @@ -253,10 +253,10 @@ 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. +The proposal's pull request may include changes in the same repository. Please +be thoughtful about how much effort you invest this way: it can help illustrate +the intent of a proposal and avoid duplicating text in the proposal, but +proposals may also need to be rewritten substantially or be deferred/declined. 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 @@ -338,8 +338,9 @@ believe more changes are needed. When significant alternatives are pointed out, include them in the proposal regardless of whether they're adopted. The "alternatives" section should be used to document rejected alternatives as well as the original approach when an -alternative is adopted, with pros and cons either way. New "open questions" may -also be added where the author isn't confident about the best approach. +alternative is adopted, with advantages and disadvantages either way. New "open +questions" may also be added where the author isn't confident about the best +approach. ##### Actions diff --git a/docs/project/goals.md b/docs/project/goals.md index fd59c8e729f7..94ff0a0cc908 100644 --- a/docs/project/goals.md +++ b/docs/project/goals.md @@ -233,7 +233,7 @@ Titus Winters writes in "Non-Atomic Refactoring and Software Sustainability": > compatibility over time, dealing with changes to underlying infrastructure and > dependencies, and working with legacy code or data. Fundamentally, it is a > different task to produce a programming solution to a problem (that solves the -> current [instance] of the problem) vs. an engineering solution (that solves +> current [instance] of the problem) versus an engineering solution (that solves > current instances, future instances that we can predict, and - through > flexibility - allows updates to solve future instances we may not be able to > predict). @@ -364,8 +364,8 @@ cost. **Adhere to the principle of least surprise.** Defaults should match typical usage patterns. Implicit features should be unsurprising and expected, while explicit syntax should inform the reader about any behavior which might -otherwise be surprising. The core concepts of implicit vs. explicit syntax are -well articulated in +otherwise be surprising. The core concepts of implicit versus explicit syntax +are well articulated in [the Rust community](https://blog.rust-lang.org/2017/03/02/lang-ergonomics.html#implicit-vs-explicit), although we may come to different conclusions regarding the principles. diff --git a/docs/project/pull_request_workflow.md b/docs/project/pull_request_workflow.md index a2e8253b8d73..4a788790a3f2 100644 --- a/docs/project/pull_request_workflow.md +++ b/docs/project/pull_request_workflow.md @@ -75,8 +75,8 @@ change seems trivial, still go through a pull request -- it'll likely be trivial to review. Always wait for someone else to review your pull request rather than just merging it, even if you have permission to do so. -Our GitHub repos are configured to require pull requests and review before they -are merged, so this rule is enforced automatically. +Our GitHub repositories are configured to require pull requests and review +before they are merged, so this rule is enforced automatically. ## Small, incremental changes diff --git a/proposals/README.md b/proposals/README.md index dcb07248cc79..d31b5d1b567f 100644 --- a/proposals/README.md +++ b/proposals/README.md @@ -6,7 +6,7 @@ Exceptions. See /LICENSE for license information. SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception --> -This directory contains accepted proposals for the carbon-lang repo. For +This directory contains accepted proposals for the carbon-lang repository. For information about declined/deferred proposals, please view the proposal's original pull request. @@ -15,8 +15,8 @@ request: - `p####.md` will contain the main proposal text. - `p####-decision.md` documents the decision and rationale. -- `p####` may be present as an optional subdirectory for related files (e.g., - images). +- `p####` may be present as an optional subdirectory for related files (for + example, images). ## Proposal list diff --git a/proposals/p0029.md b/proposals/p0029.md index c6579cb374ad..2fb8f50767c6 100644 --- a/proposals/p0029.md +++ b/proposals/p0029.md @@ -89,13 +89,13 @@ LLVM allows directly pushing/submitting to their "trunk" with post-commit review. LLVM enforces linear history for day-to-day development. Merge commits are allowed for rare events like contributing a new subproject. -Pros: +Advantages: - Still has linear history. - Incentivizes squashing for continuous integration and bisection. - Very low overhead for fixing trivial mistakes. -Cons: +Disadvantages: - Creates extremely bad incentives around code review. - Lots of patches don't get pre-commit review, even if they would benefit @@ -113,7 +113,7 @@ Cons: Classically, Git and GitHub support merging entire complex graphs of development. -Pros: +Advantages: - Mostly supported by pull requests, so still able to use much of that functionality. @@ -125,7 +125,7 @@ Pros: - Most of the time these aren't so complex that they create problems for humans. -Cons: +Disadvantages: - History is harder for humans to understand and reason about in complex cases. @@ -146,7 +146,7 @@ branching and merging within a PR, or merging `trunk` into PR is not allowed. In this model, the only merge commits are merges of PRs into `trunk`. PRs themselves don’t contain merge commits. -Pros: +Advantages: - Mostly supported by GitHub pull requests, so still able to use much of that functionality. @@ -154,8 +154,8 @@ Pros: merge commits on the trunk branch. PRs themselves can’t contain merge commits. -Cons: +Disadvantages: - Requires a custom presubmit on GitHub that checks linearity of a PR. -- The cons of the fork and merge strategy regarding the complexity of history - remain, but to a smaller degree, since non-linearity is restricted. +- The disadvantages of the fork and merge strategy regarding the complexity of + history remain, but to a smaller degree, since non-linearity is restricted. diff --git a/proposals/p0042.md b/proposals/p0042.md index 110053b5ac04..d87565504ad4 100644 --- a/proposals/p0042.md +++ b/proposals/p0042.md @@ -64,9 +64,9 @@ included directly, and carbon-language/carbon-toolchain#1 updates the ### Post-commit review Some projects, such as LLVM, use _post-commit_ review for some changes. This has -both pros and cons. +both advantages and disadvantages. -Pros: +Advantages: - Enables sustaining velocity in the face of high latency in code review. - Little need to rebase or resolve merge conflicts due to immediately @@ -75,7 +75,7 @@ Pros: - Optimizes commit velocity amongst a small group of developers with extensive experience working together and minimal review comments on others' code. -Cons: +Disadvantages: - Does not meaningfully scale beyond small group of developers with pre-existing shared understanding of desired form of code. @@ -100,7 +100,7 @@ changes for which "no functionality changes" or NFC commits. Common examples are reformatting or basic code cleanup. The idea is that these are exceedingly lower risk compared changes to functionality. -Pros: +Advantages: - Can avoid waiting for a review on trivial cleanups and refactorings. - May be especially useful as they tend to be merge conflict prone and @@ -113,7 +113,7 @@ Pros: is easier than deciding "given that it changes behavior, is the change good?". -Cons: +Disadvantages: - No concrete and objective rubric for whether or not a change is NFC, and whether it perhaps is significant enough to still warrant review. diff --git a/proposals/p0044.md b/proposals/p0044.md index 6f753dffc140..3aa92dcc05c7 100644 --- a/proposals/p0044.md +++ b/proposals/p0044.md @@ -20,11 +20,11 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception - [Option: Google Docs-centric flow](#option-google-docs-centric-flow) - [Overview](#overview-1) - [Flow summary](#flow-summary) - - [Pros/Cons](#proscons) + - [Advantages/Disadvantages](#advantagesdisadvantages) - [Option: GitHub Markdown-centric flow](#option-github-markdown-centric-flow) - [Overview](#overview-2) - [Flow summary](#flow-summary-1) - - [Pros/Cons](#proscons-1) + - [Advantages/Disadvantages](#advantagesdisadvantages-1) - [Details](#details) - [Carbon language shared drive](#carbon-language-shared-drive) - [Main shared drive](#main-shared-drive) @@ -33,7 +33,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception - [Google Docs proposal ACLs](#google-docs-proposal-acls) - [Markdown-specific questions](#markdown-specific-questions) - [Open question: Where should proposals be stored in GitHub?](#open-question-where-should-proposals-be-stored-in-github) - - [Option: Proposal archive GitHub repo (carbon-proposals)](#option-proposal-archive-github-repo-carbon-proposals) + - [Option: Proposal archive GitHub repository (carbon-proposals)](#option-proposal-archive-github-repository-carbon-proposals) - [Option: Store proposals in the repository they affect](#option-store-proposals-in-the-repository-they-affect) - [Open question: Should we push comments to focus on GitHub?](#open-question-should-we-push-comments-to-focus-on-github) - [Common principles](#common-principles) @@ -114,7 +114,7 @@ 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. +for any Google Docs we may create, and a Proposal archive GitHub repository. ### Open question: Do we use a Google Docs-centric or GitHub Markdown-centric flow? @@ -146,7 +146,7 @@ For reviewing a proposal: - 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. +- A PDF is saved to the carbon-proposals GitHub repository. - The author converts any long-term documentation portions of the doc to Markdown. @@ -160,9 +160,9 @@ If the proposal needs to be checked later to figure out why a decision was made: Since most people will have comment-only or view-only access to reviewed docs, we should treat edit history as not accessible. -##### Pros/Cons +##### Advantages/Disadvantages -Pros: +Advantages: - Supports collaborative editing. - Commenting in Docs is a slightly better UI, even though the commenting @@ -178,7 +178,8 @@ Neutral: - 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" + - for example, "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. @@ -192,7 +193,7 @@ Neutral: original state of the doc that's been suggested on, and it's not clear how the author will respond. -Cons: +Disadvantages: - Documents will go through at least three different file formats (Docs, PDF, Markdown). @@ -216,8 +217,8 @@ Cons: - 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. + the Proposal archive GitHub repository 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, @@ -241,10 +242,10 @@ Cons: 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. + may need to rewrite in bulk, for example 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. @@ -280,7 +281,7 @@ Cons: ##### Overview - Draft proposals: Markdown, possibly in Google Docs (but not required) -- Under review proposals: Markdown with review comments via GitHub +- Under review proposals: Markdown with review comments by way of GitHub - Archive proposals: Markdown - Final format: Markdown @@ -292,7 +293,7 @@ For reviewing a proposal: - 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. + GitHub repository. - 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 @@ -306,9 +307,9 @@ If the proposal needs to be checked later to figure out why a decision was made: - The pull request will have edit history publicly visible. - GitHub has a nice renderer for markdown diffs. -##### Pros/Cons +##### Advantages/Disadvantages -Pros: +Advantages: - No need to convert file formats. - Markdown reviews can be committed directly, putting all history in one @@ -352,7 +353,7 @@ Neutral: - For other readers, this is likely a pro: the current state of the doc remains visible. -Cons: +Disadvantages: - GitHub comments on pull requests can be difficult to find in certain situations. @@ -363,7 +364,7 @@ Cons: - 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 + added to explain the proposal. that is, this may be extra work without later benefit. ## Details @@ -447,7 +448,7 @@ Access controls: **Decision**: Store proposals in the repository they affect -#### Option: Proposal archive GitHub repo (carbon-proposals) +#### Option: Proposal archive GitHub repository (carbon-proposals) In this approach, the review managers are presumed to be responsible for commits to the proposal archive. @@ -456,25 +457,26 @@ Access controls: - Commit privileges: review managers -Pros: +Advantages: - Easy to find pending proposals; just look at the carbon-proposals issue tracker. - All proposals will be uniquely numbered. - No need for a proposal label: everything's a proposal. -Cons: +Disadvantages: -- Proposals affect other repos; may miss opportunities to combine changes. +- Proposals affect other repositories; may miss opportunities to combine + changes. - Harder to filter for proposals that are relevant to a specific repository. #### Option: Store proposals in the repository they affect 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. +affect. for example, 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 @@ -497,7 +499,7 @@ Access controls: - Commit privileges: normal repository access, possibly with review managers getting broad access in order to finalize proposals. -Pros: +Advantages: - Makes it easier to demonstrate the actual changes a proposal suggests making. @@ -507,17 +509,19 @@ Pros: changes_ on a single review thread, for most cases. - Makes it easy to find most/all proposals relevant to a given repository. -Cons: +Disadvantages: -- Proposals would need to be tracked separately per-repo. - - This could also end up being a pro if we get a bunch of different repos, - as it may become easier to find relevant proposals for a given repo. - It's only really a con for as long as we have few repos (which may last - long-term, as having many repos may lead to other scaling problems). -- Access controls are part of the parent repo, and so will be less restricted - than if we had a separate proposals repo. +- Proposals would need to be tracked separately per-repository. + - This could also end up being a pro if we get a bunch of different + repositories, as it may become easier to find relevant proposals for a + given repository. It's only really a con for as long as we have few + repositories (which may last long-term, as having many repositories may + lead to other scaling problems). +- Access controls are part of the parent repository, and so will be less + restricted than if we had a separate proposals repository. - Proposals won't be uniquely numbered. - - We'll need to refer to proposals with the repo, e.g., `carbon-lang/456`. + - We'll need to refer to proposals with the repository, for example, + `carbon-lang/456`. - Need to make sure we have a proposal label, to separate from non-proposal traffic. @@ -527,8 +531,8 @@ Cons: #### Common principles -- Proposals will be declared on Discourse Forums at important stages; e.g., - asking for input on ideas, RFC, decisions, etc. +- Proposals will be declared on Discourse Forums at important stages; for + example, asking for input on ideas, RFC, decisions, etc. - Some discussion is expected to occur on the GitHub PR. #### Option: Push high-level comments to Discourse Forums @@ -536,7 +540,7 @@ Cons: We could push for high-level comments to be added on the same thread as the Discourse Forums RFC. -Pros: +Advantages: - Discourse Forums offer better interfaces for pure, non-code-comment discussion. @@ -547,7 +551,7 @@ Pros: - May also be better for people used to using email lists to discuss proposed changes. -Cons: +Disadvantages: - Leads contributors to two different places for comments - some high-level discussion will inevitably be in GitHub. @@ -558,12 +562,12 @@ Cons: We could push for high-level comments to be added to the proposal PR, with other discussion. -Pros: +Advantages: - The GitHub PR becomes a single hub for conversation. - More familiar for people familiar with GitHub-only workflows. -Cons: +Disadvantages: - Discourse Forum topics cannot have "create" without "reply" permissions, so some high-level discussion will inevitably be in Discourse Forums. @@ -572,7 +576,8 @@ Cons: - Email notifications include only the lines of code affected, not what is being replied to. This will generally make it infeasible to get context from emails. -- Comment threads sometimes make it unclear what's being replied to. e.g., +- Comment threads sometimes make it unclear what's being replied to. for + example, https://github.com/carbon-language/carbon-proposals/pull/5#discussion_r423401993 and ttps://github.com/carbon-language/carbon-proposals/pull/5/files/a51ff951561accfb4aee403d7add6e8e69009ce1#r423401993 @@ -593,16 +598,16 @@ Cons: Rather than trying to guide high-level discussion to a particular medium, we could offer no guidance. -Pros: +Advantages: - Less policies, more freedom. - Discover what happens, switch back and forth over time based on individual contributor preferences. -Cons: +Disadvantages: -- Pros of a primary hub are discarded. Cons of multiple hubs should be assumed - to remain. +- Advantages of a primary hub are discarded. Disadvantages of multiple hubs + should be assumed to remain. ### Open question: Should there be a tracking issue? @@ -618,27 +623,27 @@ Cons: In a workflow where there's always a tracking issue: -1. Create the tracking issue, e.g. #123. -2. Create the PR, e.g. #456, naming the proposal p0123.md after the tracking - issue. +1. Create the tracking issue, for example #123. +2. Create the PR, for example #456, naming the proposal p0123.md after the + tracking issue. 1. Use GitHub features to link #123 and #456. 3. Update the status in p0123.md and labels of #123 when progressing a proposal. -4. When a decision is made, create a new PR, e.g. #789, containing the decision - p0123-decision.md. +4. When a decision is made, create a new PR, for example #789, containing the + decision p0123-decision.md. 1. This does not replace the Discourse Forum topic announcing a decision. 2. Use GitHub features to link #123 and #789. 3. Comments on the decision may go on the decision PR, similar to the proposal PR discussion. 5. Declined/deferred proposals may be committed or not; it doesn't matter. -Pros: +Advantages: - Easy to find the full decision in p0123-decision.md. - The PR to create the decision is clearly visible in the associated tracking issue. -Cons: +Disadvantages: - The tracking issue separates more state. @@ -647,7 +652,7 @@ Cons: In a workflow where there's no need for a tracking issue (although contributors may create them for bucketing work, they are non-essential): -1. Create the PR, e.g. #456, naming the proposal p0456.md. +1. Create the PR, for example #456, naming the proposal p0456.md. 2. Update the labels of #456 when progressing a proposal. 1. Don't bother putting the status in p0456.md: people should rely on the PR labels since it's in the same place. @@ -659,12 +664,12 @@ may create them for bucketing work, they are non-essential): 4. If declined/deferred proposals are committed, it would be best to add a status in p0456.md before committing. -Pros: +Advantages: - Lighter weight process: no tracking issue, and no need to update status in p0456.md. -Cons: +Disadvantages: - Harder to store the decision in a way that clearly links it to the original proposal. @@ -698,13 +703,13 @@ the PR is abandoned and we at most save a link to it. Note that GitHub does (at least to some extent) retain closed PRs, even those coming from a fork. -Pros: +Advantages: - The proposals directory remains a list of only accepted proposals. - No need to spend effort saving declined/deferred proposals. \ -Cons: +Disadvantages: - Lose an easy way to check declined/deferred proposals for history. - More reliance on searching forums for history. @@ -713,11 +718,11 @@ Cons: Under this approach, declined/deferred proposals are committed. -Pros: +Advantages: - Easy to skim through declined/deferred proposals. -Cons: +Disadvantages: - Finding accepted proposals may become more difficult. - Could put declined/deferred proposals in a different directory. @@ -744,8 +749,9 @@ which is for anybody in the community to easily create proposals. ### 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 +same input. for example, 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. @@ -805,11 +811,11 @@ 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: +Advantages: - Provides easy conversion of Google Docs to Markdown. -Cons: +Disadvantages: - ? @@ -821,12 +827,12 @@ This is another code formatting tool, but doesn't seem to work as well as Google's internal-only equivalent. Google's internal-only equivalent happens to do some syntax highlighting, whereas Code blocks does none. -Pros: +Advantages: - Public code formatting. - Works with "Docs to Markdown" plugin to get ```-block escaping. -Cons: +Disadvantages: - Mediocre syntax highlighting for Carbon. - No inline `foo` highlighting, unlike Google's internal-only equivalent. @@ -839,11 +845,11 @@ https://gsuite.google.com/marketplace/app/advanced_find_replace/11210842879 Advanced Find & Replace offers more advanced functionality than the built-in features, particularly around URL and regexp support. -Pros: +Advantages: - Offers improved functionality around key Google Docs friction problems. -Cons: +Disadvantages: - 2 of 5 stars: we should not expect quality. - \$6 purchase price may turn off contributors. @@ -861,12 +867,12 @@ 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: +Advantages: - Provides preview when editing Markdown files. - Provides application-specific comment support. -Cons: +Disadvantages: - Cannot use shared Google workspaces with Google corp accounts, due to security restrictions. Will likely cause issues for others, too. diff --git a/proposals/p0044_decision.md b/proposals/p0044_decision.md index c0d8205cd831..e6e7dc142d1c 100644 --- a/proposals/p0044_decision.md +++ b/proposals/p0044_decision.md @@ -78,9 +78,10 @@ etc. In general, the PR-centric model was favored. - No outdated versions in the old format left behind - The technical flow seems on balance better than the Google Docs-based - workflow. The proposal does a really good job explaining pros and cons. In - summary, the Google Docs-centric workflow has a lot of cons that make it - difficult to work with proposals over the long term. + workflow. The proposal does a really good job explaining advantages and + disadvantages. In summary, the Google Docs-centric workflow has a lot of + disadvantages that make it difficult to work with proposals over the long + term. ### Rationale for not requiring tracking issues diff --git a/proposals/p0051.md b/proposals/p0051.md index f0793f3ebb5f..872c3c6fa2af 100644 --- a/proposals/p0051.md +++ b/proposals/p0051.md @@ -91,14 +91,14 @@ While the proposers prefer the first interpretation, the second all-or-nothing interpretation may be what's leading to the desire of treating interoperability as a higher priority. -Overall, we would present the pros and cons as: +Overall, we would present the advantages and disadvantages as: -Pros: +Advantages: - There is a consensus that interoperability is critical. Making it the top goal emphasizes that. -Cons: +Disadvantages: - While interoperability is critical, the same is true of other goals; this isn't enough to determine priority. @@ -167,11 +167,11 @@ The project goals could be addressed as-is in the proposal. We could completely remove the project goals from this document. -Pros: +Advantages: - Allows this to be the "language goals" document. -Cons: +Disadvantages: - Creates additional documents that need to be understood to parse language goals. @@ -182,11 +182,11 @@ Cons: We could make the project goals part of the priority list. -Pros: +Advantages: - Makes the ordering unambiguous. -Cons: +Disadvantages: - Makes what's currently a numerated list of language design goals less design-focused. @@ -199,14 +199,14 @@ Cons: Originally, we only had one goals and priorities section. We could re-merge project goals and language goals. -Pros: +Advantages: - Makes the document shorter and more concise. - Tooling can already be considered a priority under "Code that is easy to read, understand, and write", and is explicitly mentioned as part of that goal. -Cons: +Disadvantages: - Previous setup raised objections over why the community goal wasn't part of the priority list. diff --git a/proposals/p0083.md b/proposals/p0083.md index c088a885a8d2..8feee2883379 100644 --- a/proposals/p0083.md +++ b/proposals/p0083.md @@ -79,12 +79,12 @@ We also considered putting the full design overview in one file, as in [PR 22](https://github.com/carbon-language/carbon-lang/pull/22). This is versus the hierarchy proposed here. -Pros: +Advantages: - All proposed changes are in one place. - Easier for people to skim rationale and considered changes. -Cons: +Disadvantages: - Encourages more single-file designs. - A principle of the multi-file approach is that complex features may have @@ -99,13 +99,13 @@ The primary alternative is to avoid even having a draft or in-progress design of this form until each constituent component is more thoroughly conceived and considered. -Pros: +Advantages: - Avoids anchoring design on approaches that haven't yet been fully explored. - Avoids getting stuck on discussing details where a proposal isn't fleshed out. -Cons: +Disadvantages: - The lack of an overview can lead to significant confusion and inconsistencies in discussion, hindering fleshing out details. @@ -131,13 +131,13 @@ additional content. The proposed approach assumes that the proposed overviews offer significant value for ramp-up. -Pros: +Advantages: - Eliminates content duplication. - A simple index is easier to maintain long-term, with less to become stale. - It could be fully automated. -Cons: +Disadvantages: - No quick way to get a high-level understanding. - The overview is the only step before "reading every design". diff --git a/proposals/p0107.md b/proposals/p0107.md index 1a34e9b42d2d..6869176ccbc8 100644 --- a/proposals/p0107.md +++ b/proposals/p0107.md @@ -103,7 +103,7 @@ Keep `package`. Right now, the `package` syntax requires the package's own name be repeated through code. This touches on a couple alternatives: -- Strict association between the filesystem path and library/namespace +- Strict association between the file system path and library/namespace - [Referring to the package as `package`](/docs/design/code_and_name_organization.md#referring-to-the-package-as-package) The end result of taking both alternatives would be that: diff --git a/proposals/p0142.md b/proposals/p0142.md index d55b69be43b0..aa2f302e40c6 100644 --- a/proposals/p0142.md +++ b/proposals/p0142.md @@ -83,7 +83,7 @@ Regardless of how program text is concretely stored, the first step in processing any such text is to convert it to a sequence of Unicode code points -- although such conversion may be purely notional. The result of this conversion is a Carbon _source file_. Depending on the needs of the language, we -may require each such source file to have an associated file name, even if the +may require each such source file to have an associated filename, even if the source file does not originate in anything resembling a file system. ### Normalization @@ -153,7 +153,7 @@ permitted in identifiers in C++20. Similarly, it indicates which characters should be classified as whitespace, including all the ASCII whitespace characters plus some non-ASCII whitespace characters. It also supports language-specific "profiles" to alter these baseline character sets for the -needs of a particular language -- for instance, to permit underscores in +needs of a particular language -- for example, to permit underscores in identifiers, or to include non-breaking spaces as whitespace characters. This proposal does not specify concrete choices for lexical rules, nor that we diff --git a/proposals/p0149.md b/proposals/p0149.md index 5216150ad51c..97de66da1ac0 100644 --- a/proposals/p0149.md +++ b/proposals/p0149.md @@ -116,6 +116,8 @@ https://docs.microsoft.com/en-us/style-guide/welcome/ > may be that Microsoft has other noteworthy guidance for terms that Google > doesn't. + + above : Google: Use preceding. @@ -296,6 +298,8 @@ vs. : Microsoft: Use versus. + + ## Alternatives considered Various offline resources like the Chicago Manual of Style may be helpful to