Skip to main content
Version: 2.5 (deprecated)

Contribution overview

The flow for making changes to Pants.

We welcome contributions of all types: from fixing typos to bug fixes to new features. For further questions about any of the below, please refer to the community overview.

Help wanted: identifying bad error messages

We strive—but sometimes fail—to make every error message easy to understand and to give insight into what went wrong and how to fix it.

If you ever encounter a confusing or mediocre error message, we would love your help to identify the error message. Please open a GitHub issue with the original Pants command, the error message, and what you found confusing or think could be improved.

(If you'd be interested in then changing the code, we'd be happy to point you in the right direction!)

Documentation Fixes​

Pants uses readme.com for the documentation at pantsbuild.org. On any of these docs pages, you can click "Suggest Edits" at the top right corner in order to be dropped into the editor interface. You will be asked to log in or sign up to readme.com, which only asks for your email address and a name to call you.

When done with your edits to a page, you can click "Submit Suggested Edits" at the top right corner in order to send them to us for review.

Pants's tech stack​

Most of Pants is written in Python 3. The majority of contributions touch this Python codebase.

We rely on several Python features that you will want to acquaint yourself with:

Pants's engine is written in Rust. See Developing Rust for a guide on making changes to the internals of Pants's engine.

First, share your plan​

Before investing your time into a code change, it helps to share your interest. This will allow us to give you initial feedback that will save you time, such as pointing you to related code.

To share your plan, please either open a GitHub issue or message us on Slack (you can start with the #general channel). Briefly describe the change you'd like to make, including a motivation for the change.

If we do not respond within 24 business hours, please gently ping us by commenting "ping" on your GitHub issue or messaging on Slack asking if someone could please take a look.

Tip: Can you split out any "prework"?

If your change is big, such as adding a new feature, it can help to split it up into multiple pull requests. This makes it easier for us to review and to get passing CI.

This is a reason we encourage you to share your plan with us - we can help you to scope out if it would make sense to split into multiple PRs.

Developing your change​

To begin, set up Pants on your local machine.

To run a test, run:

$ ./pants test src/python/pants/util/frozendict_test.py

Periodically, you will want to run MyPy and the autoformatters and linters:

# Format un-committed changes
$ ./pants --changed-since=HEAD fmt

# Run the pre-commit checks, including `typecheck` and `lint`
$ build-support/githooks/pre-commit

See our Style guide for some Python conventions we follow.

You can share works in progress!

You do not need to fully finish your change before asking for feedback. We'd be eager to help you while iterating.

If doing this, please open your pull request as a "Draft" and prefix your PR title with "WIP". Then, comment on the PR asking for feedback and/or post a link to the PR in Slack.

Opening a pull request​

When opening a pull request, start by providing a concise and descriptive title. It's okay if you aren't sure what to put - we can help you to reword it.

Good titles:

  • Fix typo in strutil.py
  • Add Thrift code generator for Python
  • Fix crash when running test with Python 3.9

Bad titles:

  • Fix bug
  • Fix #8313
  • Add support for Thrift code generation by first adding the file codegen.py, then hooking it up, and finally adding tests

Then, include a description. You can use the default template if you'd like, or use a normal description instead. Link to any corresponding GitHub issues.

Tip: Review your own PR

It is often helpful to other reviewers if you proactively review your own code. Specifically, add comments to parts where you want extra attention.

For example:

  • "Do you know of a better way to do this? This felt clunky to write."
  • "This was really tricky to figure out because there are so many edge cases. I'd appreciate extra attention here, please."
  • "Note that I did not use a dataclass here because I do not want any of the methods like __eq__ to be generated."
FYI: we squash merge

This means that the final commit message will come from your PR description, rather than your commit messages.

Good commit messages are still very helpful for people reviewing your code; but, your PR description is what will show up in the changelog.

CI​

We use GitHub Actions for CI. Look at the "Checks" tab of your PR.

Review feedback​

One or more reviewers will leave feedback. If you are confused by any of the feedback, please do not be afraid to ask for clarification!

If we do not respond within 24 business hours, please gently ping us by commenting "ping" on your pull request or messaging on Slack asking if someone could please take a look.

Once one or more reviewers have approved—and CI goes green—a reviewer will merge your change.

When will your change be released?

Your change will be included in the next weekly dev release, which usually happens every Friday or Monday. If you fixed a bug, your change may also be cherry-picked into a release candidate from the prior release series.

See Release strategy.