carbon-lang/docs/project/contribution_tools.md

Contribution tools

The Carbon language project has a number of tools used to assist in preparing contributions.

Table of contents

• pre-commit
• black
• codespell
• markdown-toc
• Prettier
  • vim-prettier

pre-commit

We use pre-commit to run various checks. This will automatically run important checks, including formatting.

To set up pre-commit:

• Follow the installation instructions.
• Enable per-repo: pre-commit install
  • We already have pre-commit configured for Carbon repos -- do not go through the Quick start instructions.
• pre-commit may be run either automatically with git commit or manually with pre-commit run.
  • When files are modified, including by pre-commit failures, git add will need to be run to include the modifications in the commit, and the commit re-started.

When modifying or adding pre-commit hooks, please run pre-commit run --all-files to see what changes.

black

pre-commit enabled: If you're using pre-commit, it will run this. Installing and running manually is optional, but may be helpful.

We use Black to format Python code. Although Prettier is used for most languages, it doesn't support Python.

codespell

pre-commit enabled: If you're using pre-commit, it will run this. Installing and running manually is optional, but may be helpful.

We use codespell to spellcheck common errors. This won't catch every error; we're trying to balance true and false positives.

markdown-toc

pre-commit enabled: If you're using pre-commit, it will run this. Installing and running manually is optional, but may be helpful.

We use markdown-toc to provide GitHub-compatible tables of contents for some documents.

If run manually, specify --bullets=- to use Prettier-compatible bullets, or always run Prettier after markdown-toc.

Prettier

pre-commit enabled: If you're using pre-commit, it will run this. Installing and running manually is optional, but may be helpful.

We use Prettier for formatting. There is an rc file for configuration.

vim-prettier

If you use vim-prettier, the .prettierrc.yaml should still apply as long as config_precedence is set to the default file-override. However, we may need to add additional settings where the vim-prettier default diverges from prettier, as we notice them.