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

Automated fixes using check-google-doc-style (#193)

Browse Source 
With one manual ignore in the markdown style proposal, because it's explicitly listing disallowed terms.
This commit is contained in:
Jon Meow
2020-11-12 10:31:26 -08:00
committed by GitHub
parent bb1ad5478f
commit 94e065d9d2
21 changed files with 168 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/code_and_name_organization/README.md
+15 -15
View File
@@ -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 `/`.
docs/design/name_lookup.md
+1 -1
View File
@@ -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.
docs/design/primitive_types.md
+1 -1
View File
@@ -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
docs/design/structs.md
+3 -3
View File
@@ -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
docs/design/syntactic_conventions.md
+5 -5
View File
@@ -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).
docs/project/commenting_guidelines.md
+2 -2
View File
@@ -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.
docs/project/consensus_decision_making.md
+4 -3
View File
@@ -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
docs/project/contribution_tools.md
+3 -3
View File
@@ -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
docs/project/evolution.md
+7 -6
View File
@@ -253,10 +253,10 @@ community's engagement in it. Beyond the above structure, try to use
or [BLUF](<https://en.wikipedia.org/wiki/BLUF_(communication)>) 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
docs/project/goals.md
+3 -3
View File
@@ -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.
docs/project/pull_request_workflow.md
+2 -2
View File
@@ -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
proposals/README.md
+3 -3
View File
@@ -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
proposals/p0029.md
+8 -8
View File
@@ -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.
proposals/p0042.md
+5 -5
View File
@@ -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.
proposals/p0044.md
+80 -74
View File
@@ -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.
proposals/p0044_decision.md
+4 -3
View File
@@ -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
proposals/p0051.md
+9 -9
View File
@@ -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.
proposals/p0083.md
+6 -6
View File
@@ -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".
proposals/p0107.md
+1 -1
View File
@@ -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:
proposals/p0142.md
+2 -2
View File
@@ -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
proposals/p0149.md
+4
View File
@@ -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.
<!-- google-doc-style-ignore -->
above
: Google: Use preceding.
@@ -296,6 +298,8 @@ vs.
: Microsoft: Use versus.
<!-- google-doc-style-resume -->
## Alternatives considered
Various offline resources like the Chicago Manual of Style may be helpful to