Skip to main content
Version: 2.32 (prerelease)

Contribution overview

Making changes to Pants.

We welcome contributions of all types: from fixing typos to bug fixes to new features.

First, discuss your plan​

Before investing in a code change, please discuss your plan with us first. This allows us to give you initial feedback that will save you and us time and effort.

To share your plan, please open a GitHub issue, and then message us on the #development channel on Slack.

If you're new to the Pants developer community, please take a moment to introduce yourself and tell us about your Pants usage. Describe the change you'd like to make and why you want to make it, and link to the GitHub issue.

If we do not respond within 2-3 days, please gently remind us on Slack.

LLM Assistance Notice​

AI/LLM assisted code contributions are welcome. That includes using LLM assistance to write, introspect, read, reason about, debug, or test code contributions. However, the extent of the LLM generation must be disclosed in the Pull Request description. All of the normal expectations of a human apply: you need to understand it, have tested it, and be able to discuss the proposed change.

None of this is meant to discourage LLM use -- it is not frowned upon! -- but it is critical context for reviewers. One of the most valuable community actions is careful, line-by-line review of an earnest first-time contribution. That takes a lot of time and care. But that effort doesn't help a robot, and different modes of feedback are more appropriate.

An example disclosure:

This PR was written primarily by Claude Code.

Or:

ChatGPT looked for prior art and came up with the approach but I wrote the code manually.

Or:

I used an LLM to generate all of the test cases first, and then I wrote the code.

Or:

<Inline comments calling out specific parts of the PR>

Minor exceptions to this policy include basic auto-complete functionality or the various Machine Learning techniques that are no longer called "AI". Spellcheck is not an AI.

To put all this in more general terms, some projects have a convention of every commit using a "Test Plan" where one would include a screenshot showing that the new website feature really did render correctly. With the expanded use of LLMs, prose that serves as a "Test Plan" for the change itself -- not just for code correctness -- becomes more valuable. Use the disclosure as an opportunity to verify the conceptual soundness of the change.

AI/LLM generation is for code changes only. All community interactions, including comments, discussion, issues, PR titles, and descriptions must be composed by a human. Slack chat is for humans, there are now countless other services if you want a chatbot. Be respectful to one another and mindful of the person on the other end.

An exception is LLM-assisted translations. Please note when this is in use (ex: "I am translating from LANGUAGE with an LLM").

This policy was inspired by the ghostty AI Assistance Notice and the Jellyfin LLM/"AI" Development Policy. For further discussion of LLM prose and social contracts, see Using LLMs at Oxide.

Documentation Fixes​

To suggest edits to Pants documentation, fork the Pants repository, make changes to files in the docs/ directory, and submit a PR against the main branch. Address feedback from maintainers and, once approved, your changes will be incorporated into the official documentation.

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.

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.

Design docs​

Changes that substantially impact the user experience, APIs, design or implementation, may benefit from a design doc that serves as a basis for discussion.

We store our design docs in this Google Drive folder. If you want to write a design doc, let us know and if necessary we can give you write access to that folder.

We don't currently have any guidelines on the structure or format of design docs, so write those as you see fit.

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-push checks, including `check` and `lint`
$ build-support/githooks/pre-push

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.

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!)

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.

Flaky tests?

We unfortunately have some flaky tests. If CI fails and you believe it is not related to your change, please comment about the failure so that a maintainer may investigate and restart CI for you.

Alternatively, you can push an empty commit with git commit --allow-empty to force CI to restart. Although we encourage you to still point out the flake to us.

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.

Release notes​

We maintain release notes as we go: every pull request should add or adjust the release notes if required. These release notes are files in docs/notes/, grouped by release series; for example, docs/notes/2.22.x.md includes the release notes for 2.22 releases.

The release note file is generally grouped by "backend". If you're not sure whether to add release notes, or where to put them, or how to phrase them, feel free to:

  • look in other release notes files in docs/notes for inspiration
  • ask in #development on Slack
  • open a pull request and ask the reviewers

New features and major bug fixes should definitely have release notes, but other changes can opt out. For example, fixes to features that aren't released or minor documentation fixes.

We have guidance to walk us through this, so it's not a problem to forget. Pull request CI enforces that either:

  • the PR has release notes, by having changes in docs/notes/
  • someone has opted out, by labelling the PR with release-notes:not-required or category:internal (the latter means that release notes are optional for all category:internal PRs).

For minor releases, all GitHub release description will simply list all the commits save those with release-notes:not-required or category:internal.