Pants Contributors Guide
This page documents how to make contributions to Pants. If you've developed a change to Pants, it passes all tests, and you'd like to "send it upstream", here's what to do:
Questions, Issues, Bug Reports
See How To Ask
Join the Conversation
Join the pants-devel Google Group to keep in touch with other pants developers.
Join the pantsbuild Slack team and hop on the
#general channel for higher bandwidth questions and answers about hacking on
or using pants. You can send yourself an invite or ask for one
on the pants-devel Google group.
Watch the pantsbuild/pants Github project for notifications of new issues, etc.
Follow @pantsbuild on Twitter for occasional announcements.
Find out when the CI tests go red/green by adding your email address to .travis.yml.
Life of a Change
Let's walk through the process of making a change to pants. At a high level, the steps are:
- Identify the change you'd like to make (e.g.: fix a bug, add a feature).
- Get the code.
- Make your change on a branch.
- Get a code review.
- Commit your change to master.
Identify the change
It's a good idea to make sure the work you'll be embarking on is generally agreed to be in a useful direction for the project before getting too far along.
If there is a pre-existing github issue filed and un-assigned, feel free to grab it and ask any clarifying questions needed on pants-devel. If there is an issue you'd like to work on that's assigned and stagnant, please ping the assignee and finally pants-devel before taking over ownership for the issue.
If you have an idea for new work that's not yet been discussed on pants-devel, then start a conversation there to vet the proposal. Once the group agrees it's worth a spike you can file a github issue and assign it to yourself.
Getting Pants Source Code
If you just want to compile and look at the source code, the easiest way is to clone the repo.
$ git clone https://github.com/pantsbuild/pants
If you would like to start developing patches and contributing them back, you will want to create a fork of the repo using the instructions on github.com. With this setup, you can push branches and run Travis-CI before your change is committed.
If you've already cloned your repo without forking, you don't have to re-checkout your repo. First, create the fork on github. Make a note the clone url of your fork. Then run the following commands:
$ git remote remove origin $ git remote add origin <url-to-clone-your-fork> $ git remote add upstream https://github.com/pantsbuild/pants
After this change,
git push and
git pull will go to your fork. You
can get the latest changes from the
pantsbuild/pants repo's master
branch using the syncing a
fork instructions on
Whether you've cloned the repo or your fork of the repo, you should setup the local pre-commit hooks to ensure your commits meet minimum compliance checks before pushing branches to ci:
You can always run the pre-commit checks manually via:
Pro tip: If you are certain that you have not accidentally committed anything to
master branch that you want to keep, and you want to reset to an exact copy of
pantsbuild/pants repo's master branch, use these commands:
$ git fetch upstream $ git checkout master && git reset --hard upstream/master
Making the Change
Create a new branch off master and make changes.
$ git checkout -b $FEATURE_BRANCH
Does your change alter Pants' behavior in a way users will notice? If so, then along with changing code...
- Consider updating the user documentation.
Run the CI Tests
Before posting a review but certainly before the branch ships you should run relevant tests. If you're not sure what those are, run all the tests.
Now that your change is complete, post it for review. We use
github.com pull requests
to host code reviews:
Posting the First Draft
When all of the tests are green on travis, you're probably ready to request review for the change!
To get your pull request reviewed, you should:
- Include a short and descriptive title.
- Fill in each of the sections of the pull request template, and include links to any relevant github issues for the change.
- Mention (usually in a comment on the PR) any specific
who should review your change. Running
git log -- $filenameon one or more of the files that you changed is a good way to find potential reviewers!
You can see a list of all actively
reviewable reviews here.
If reviewers post any feedback
(for more information on providing feedback see),
there might be a few iterations before finally getting a Ship It. As reviewers enter
feedback, the github page updates; it should also send
you mail as long as you are
Subscribed to notifications for the pull request.
Github pull requests currently lack the ability to mark a review comment as "blocking" for a change, so it's important for contributors and reviewers to communicate clearly which comments they view as blocking. If it's unclear whether a reviewer feels strongly about a particular point, please bias toward clearing up the uncertainty before proceeding.
If those reviews inspire you to change some code, great. Change some code and commit locally. When you're ready to update the pull request with your changes, push to the relevant branch on your fork as you did before:
$ git push <your-username> $FEATURE_BRANCH
Look over the fields in the pull request you created earlier; perhaps some could use updating.
Press the web form's
If at any point you need to make changes that will fundamentally overhaul a review,
consider temporarily removing the
reviewable label in order to let reviewers know
to hold off until the code is ready.
If your pull request fails in travis, you can look at the shard logs to see the
failure cause. From that log, you can figure out what tests you need to run to reproduce the failure
locally. If you cannot reproduce the failure locally and it looks unrelated to your change, please
open an issue for it with the label
flaky-test)[https://github.com/pantsbuild/pants/labels/flaky-test]. You can also ping slack to
ask for someone to restart the failing shard.
(More on checking CI test runs here)
Committing a Change
At this point you've made a change, had it reviewed (and received one or more Ship Its!) and are ready to complete things by getting your change in master. (If you're not a committer, please ask one to do this section for you.)
A committer should push the
Squash and merge button on the PR, and ensure that the
commit message generated from the review summary is accurate. In particular, the title should
contain a useful summary of the change, and the description should follow the pull request
template (defined in the root of the repo at
Finally, the committer will select
Confirm squash and merge. The change is now complete. Huzzah!