mirror of
https://github.com/carbon-language/carbon-lang.git
synced 2026-09-24 20:30:14 +01:00
Adjust md tab width to work better cross-markdown-parser (#124)
We're running into issues with md handlers that expect this kind of 4-space indent. It should be cross-compatible with GH, so switch, even though it feels a little churny.
Manual edits are to:
- .prettierrc.yaml:
- rename from .prettierrc
- add tabWidth (primary change)
- add trailingComma (fix vimPrettier skew)
- contribution_tools.md: Fix remarks about .prettierrc.yaml
- pre-commit-toc.js: indent, bullets
- pre-commit-proposal-list.py: indent of output
The rest is the result of `pre-commit run --all-files`
Unfortunately this'll probably depend on the change being propagated into PR branches, so I wouldn't be surprised if we see regressions for a bit. We'll also need to nudge people to update .vimrc's. Hopefully the pre-commit GH action helps catch issues.
This commit is contained in:
Jon Meow
GitHub
+90
-87
@@ -12,11 +12,11 @@ free to ask on our Discourse Forums or Discord Chat.
|
||||
|
||||
Everyone contributing to Carbon is expected to:
|
||||
|
||||
- Read and follow the [Code of Conduct](CODE_OF_CONDUCT.md). We expect everyone
|
||||
in our community to be welcoming, helpful, and respectful.
|
||||
- Ensure you have signed the
|
||||
[Contributor License Agreement (CLA)](https://cla.developers.google.com/). We
|
||||
need this to cover some legal bases.
|
||||
- Read and follow the [Code of Conduct](CODE_OF_CONDUCT.md). We expect
|
||||
everyone in our community to be welcoming, helpful, and respectful.
|
||||
- Ensure you have signed the
|
||||
[Contributor License Agreement (CLA)](https://cla.developers.google.com/).
|
||||
We need this to cover some legal bases.
|
||||
|
||||
We also encourage anyone interested in contributing to check out all the
|
||||
information here in our contributing guide, especially the
|
||||
@@ -71,13 +71,13 @@ can accept them, we need you to cover some legal bases.
|
||||
|
||||
Please fill out either the individual or corporate CLA.
|
||||
|
||||
- If you are an individual contributing to spec discussions or writing original
|
||||
source code and you're sure you own the intellectual property, then you'll
|
||||
need to sign an
|
||||
[individual CLA](https://code.google.com/legal/individual-cla-v1.0.html).
|
||||
- If you work for a company that wants to allow you to contribute your work,
|
||||
then you'll need to sign a
|
||||
[corporate CLA](https://code.google.com/legal/corporate-cla-v1.0.html).
|
||||
- If you are an individual contributing to spec discussions or writing
|
||||
original source code and you're sure you own the intellectual property, then
|
||||
you'll need to sign an
|
||||
[individual CLA](https://code.google.com/legal/individual-cla-v1.0.html).
|
||||
- If you work for a company that wants to allow you to contribute your work,
|
||||
then you'll need to sign a
|
||||
[corporate CLA](https://code.google.com/legal/corporate-cla-v1.0.html).
|
||||
|
||||
Follow either of the two links above to access the appropriate CLA and
|
||||
instructions for how to sign and return it. Once we receive it, we'll be able to
|
||||
@@ -102,41 +102,42 @@ Membership is currently invite-only.
|
||||
Before using these systems, everyone must sign the CLA. They are all governed by
|
||||
the Code of Conduct.
|
||||
|
||||
- [The GitHub carbon-language organization](https://github.com/orgs/carbon-language)
|
||||
is used for our repositories. **To join:**
|
||||
- [The GitHub carbon-language organization](https://github.com/orgs/carbon-language)
|
||||
is used for our repositories. **To join:**
|
||||
|
||||
1. Ask [an admin](docs/project/groups.md#admins) to send an invite, providing
|
||||
your GitHub account.
|
||||
2. Check your email to accept the invite, or try the standard
|
||||
[accept link](https://github.com/orgs/carbon-language/invitation?via_email=1)
|
||||
if you don't see the email.
|
||||
1. Ask [an admin](docs/project/groups.md#admins) to send an invite,
|
||||
providing your GitHub account.
|
||||
2. Check your email to accept the invite, or try the standard
|
||||
[accept link](https://github.com/orgs/carbon-language/invitation?via_email=1)
|
||||
if you don't see the email.
|
||||
|
||||
- [Discourse Forums](https://forums.carbon-lang.dev) are used for long-form
|
||||
discussions. **To join:**
|
||||
- [Discourse Forums](https://forums.carbon-lang.dev) are used for long-form
|
||||
discussions. **To join:**
|
||||
|
||||
1. Go to [the forums](https://forums.carbon-lang.dev) and register your
|
||||
GitHub account.
|
||||
- You will be able to choose which GitHub email you want the forums to
|
||||
send email to.
|
||||
2. [An admin](docs/project/groups.md#admins) will need to approve your
|
||||
registration.
|
||||
1. Go to [the forums](https://forums.carbon-lang.dev) and register your
|
||||
GitHub account.
|
||||
- You will be able to choose which GitHub email you want the forums to
|
||||
send email to.
|
||||
2. [An admin](docs/project/groups.md#admins) will need to approve your
|
||||
registration.
|
||||
|
||||
- [Discord Chat](https://discord.com/app) is used for short-form chats. **To
|
||||
join:**
|
||||
- [Discord Chat](https://discord.com/app) is used for short-form chats. **To
|
||||
join:**
|
||||
|
||||
1. Ask [an admin](docs/project/groups.md#admins) for an invite link.
|
||||
- Please do not re-share the invite links: they're our only way to
|
||||
restrict access.
|
||||
2. You will be prompted with the Code of Conduct. After reading it, click the
|
||||
check mark reaction icon at the bottom.
|
||||
1. Ask [an admin](docs/project/groups.md#admins) for an invite link.
|
||||
- Please do not re-share the invite links: they're our only way to
|
||||
restrict access.
|
||||
2. You will be prompted with the Code of Conduct. After reading it, click
|
||||
the check mark reaction icon at the bottom.
|
||||
|
||||
- [A shared Google Drive](https://drive.google.com/corp/drive/folders/0ALTu5Y6kc39XUk9PVA)
|
||||
is used for all of our Google Docs, particularly proposal drafts. **To join:**
|
||||
1. Ask [an admin](docs/project/groups.md#admins) to invite you, providing
|
||||
your Google account email.
|
||||
2. The admin will add you to the
|
||||
[Google Group](https://groups.google.com/g/carbon-lang-contributors) used
|
||||
for access.
|
||||
- [A shared Google Drive](https://drive.google.com/corp/drive/folders/0ALTu5Y6kc39XUk9PVA)
|
||||
is used for all of our Google Docs, particularly proposal drafts. **To
|
||||
join:**
|
||||
1. Ask [an admin](docs/project/groups.md#admins) to invite you, providing
|
||||
your Google account email.
|
||||
2. The admin will add you to the
|
||||
[Google Group](https://groups.google.com/g/carbon-lang-contributors)
|
||||
used for access.
|
||||
|
||||
### Contribution guidelines and standards
|
||||
|
||||
@@ -145,44 +146,46 @@ follow the Carbon documentation and coding styles.
|
||||
|
||||
#### Guidelines and philosophy for contributions
|
||||
|
||||
- For **both** documentation and code:
|
||||
- For **both** documentation and code:
|
||||
|
||||
- When the Carbon team accepts new documentation or features, to Carbon, by
|
||||
default they take on the maintenance burden. This means they'll weigh the
|
||||
benefit of each contribution must be weighed against the cost of maintaining
|
||||
it.
|
||||
- The appropriate [style](#style) is applied.
|
||||
- The [license](#license) is present in all contributions.
|
||||
- When the Carbon team accepts new documentation or features, to Carbon,
|
||||
by default they take on the maintenance burden. This means they'll weigh
|
||||
the benefit of each contribution must be weighed against the cost of
|
||||
maintaining it.
|
||||
- The appropriate [style](#style) is applied.
|
||||
- The [license](#license) is present in all contributions.
|
||||
|
||||
- For documentation:
|
||||
- For documentation:
|
||||
|
||||
- All documentation is written for clarity and readability. Beyond fixing
|
||||
spelling and grammar, this also means content is worded to be accessible to
|
||||
a broad audience.
|
||||
- Substantive changes to Carbon follow the
|
||||
[evolution process](docs/project/evolution.md). Pull requests are only sent
|
||||
after the documentation changes have been accepted by the reviewing team.
|
||||
- Typos or other minor fixes that don't change the meaning of a document do
|
||||
not need formal review, and are often handled directly as a pull request.
|
||||
- All documentation is written for clarity and readability. Beyond fixing
|
||||
spelling and grammar, this also means content is worded to be accessible
|
||||
to a broad audience.
|
||||
- Substantive changes to Carbon follow the
|
||||
[evolution process](docs/project/evolution.md). Pull requests are only
|
||||
sent after the documentation changes have been accepted by the reviewing
|
||||
team.
|
||||
- Typos or other minor fixes that don't change the meaning of a document
|
||||
do not need formal review, and are often handled directly as a pull
|
||||
request.
|
||||
|
||||
- For code:
|
||||
- For code:
|
||||
|
||||
- New features should have a documented design that has been approved through
|
||||
the [evolution process](docs/project/evolution.md). This includes
|
||||
modifications to pre-existing designs.
|
||||
- Bug fixes and mechanical improvements don't need this.
|
||||
- All new features include unit tests, as they help to (a) document and
|
||||
validate concrete usage of the feature and its edge cases, and (b) guard
|
||||
against future breaking changes to lower the maintenance cost.
|
||||
- Bug fixes also generally include unit tests, because the presence of bugs
|
||||
usually indicates insufficient test coverage.
|
||||
- Unit tests must pass with the changes.
|
||||
- If some tests fail for unrelated reasons, we wait until they're fixed. It
|
||||
helps to contribute a fix!
|
||||
- Code changes are made with API compatibility and evolvability in mind.
|
||||
Reviewers will comment on any API compatibility issues.
|
||||
- Keep in mind that code contribution guidelines are incomplete while we start
|
||||
work on Carbon, and may change later.
|
||||
- New features should have a documented design that has been approved
|
||||
through the [evolution process](docs/project/evolution.md). This
|
||||
includes modifications to pre-existing designs.
|
||||
- Bug fixes and mechanical improvements don't need this.
|
||||
- All new features include unit tests, as they help to (a) document and
|
||||
validate concrete usage of the feature and its edge cases, and (b) guard
|
||||
against future breaking changes to lower the maintenance cost.
|
||||
- Bug fixes also generally include unit tests, because the presence of
|
||||
bugs usually indicates insufficient test coverage.
|
||||
- Unit tests must pass with the changes.
|
||||
- If some tests fail for unrelated reasons, we wait until they're fixed.
|
||||
It helps to contribute a fix!
|
||||
- Code changes are made with API compatibility and evolvability in mind.
|
||||
Reviewers will comment on any API compatibility issues.
|
||||
- Keep in mind that code contribution guidelines are incomplete while we
|
||||
start work on Carbon, and may change later.
|
||||
|
||||
## pre-commit
|
||||
|
||||
@@ -204,19 +207,19 @@ Markdown files should additionally use
|
||||
|
||||
Other style points to be aware of are:
|
||||
|
||||
- Whereas the Google developer documentation style guide
|
||||
[says to use an em dash](https://developers.google.com/style/dashes)
|
||||
(`text—text`), we are using a double-hyphen with surrounding spaces
|
||||
(`text -- text`). We are doing this because we frequently read Markdown with
|
||||
fixed-width fonts where em dashes are not clearly visible.
|
||||
- Always say "Discourse Forum" and "Discord Chat" to avoid confusion between
|
||||
systems.
|
||||
- Prefer the term "developers" when talking about people who would write Carbon
|
||||
code. We expect the Carbon's community to include people who think of
|
||||
themselves using many titles, including software developers, software
|
||||
engineers, systems engineers, reliability engineers, data scientists, computer
|
||||
scientists, programmers, and coders. We're using "developers" to succinctly
|
||||
cover the variety of titles.
|
||||
- Whereas the Google developer documentation style guide
|
||||
[says to use an em dash](https://developers.google.com/style/dashes)
|
||||
(`text—text`), we are using a double-hyphen with surrounding spaces
|
||||
(`text -- text`). We are doing this because we frequently read Markdown with
|
||||
fixed-width fonts where em dashes are not clearly visible.
|
||||
- Always say "Discourse Forum" and "Discord Chat" to avoid confusion between
|
||||
systems.
|
||||
- Prefer the term "developers" when talking about people who would write
|
||||
Carbon code. We expect the Carbon's community to include people who think of
|
||||
themselves using many titles, including software developers, software
|
||||
engineers, systems engineers, reliability engineers, data scientists,
|
||||
computer scientists, programmers, and coders. We're using "developers" to
|
||||
succinctly cover the variety of titles.
|
||||
|
||||
### Other files
|
||||
|
||||
|
||||
Reference in New Issue
Block a user