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

• Main tools
  • brew
  • pyenv and Python
  • pre-commit
• Optional tools
  • Carbon-maintained
    • new_proposal.py
    • pr_comments.py
  • GitHub
    • gh CLI
    • GitHub Desktop
  • Vim
    • vim-prettier
  • Atom
  • pre-commit enabled tools
    • black
    • codespell
    • markdown-toc
    • Prettier

Main tools

These tools are key for contributions, primarily focused on validating contributions.

brew

brew is a package manager, and can help install several tools that we recommend. See the installation instructions.

pyenv and Python

pyenv is the recommended way to install Python. Our recommended way of installing both is:

brew update
brew install pyenv
pyenv install 3.8.5
pyenv global 3.8.5

# Add 'eval "$(pyenv init -)"' to your shell rc file.
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
# Load the shell rc file changes.
exec $SHELL

pre-commit

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

To set up pre-commit, see the installation instructions, or:

pip install pre-commit

# From within each carbon-language git repository:
pre-commit install

When you have changes to commit to git, a standard pre-commit workflow can look like:

# Let pre-commit fix style issues.
pre-commit run
# Add modifications made by pre-commit.
git add .
# Commit the changes
git commit

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

Optional tools

Carbon-maintained

new_proposal.py

new_proposal.py is a helper for generating the PR and proposal file for a new proposal. It's documented in the proposal template.

NOTE: This requires installing the gh CLI.

pr_comments.py

pr_comments.py is a helper for scanning comments in GitHub. It's particularly intended to help find threads which need to be resolved.

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 from the given user. For example, use when looking for threads that you still need to respond to.
• --comments-from LOGIN: Only print threads with comments from the given user. For example, use when looking for threads that you've commented on.

NOTE: This requires the Python gql package:

pip install gql

GitHub

gh CLI

The gh CLI supports some GitHub queries, and is used by some scripts.

To install gh, run:

brew update
brew install github/gh/gh

GitHub Desktop

GitHub Desktop provides a UI for managing git repositories. See the page for installation instructions.

Vim

vim-prettier

vim-prettier is a vim integration for 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.

Atom

Atom is an IDE that's mainly mentioned here for its Markdown support. See the page for installation instructions.

Some packages that may be helpful are:

• markdown-preview-enhanced: An improvement over the default-installed markdown-preview package. If using this:
  • Disable markdown-preview.
  • In the package settings, turn off 'Break On Single New Line' -- this is consistent with carbon-lang.dev and Prettier.
• prettier-atom: For Prettier integration.
• python-black: For black integration.

pre-commit enabled tools

If you're using pre-commit, it will run these tools. Installing and running them manually is optional, but may be helpful.

black

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

codespell

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

markdown-toc

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

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