Tax-Calculator Pull-Request Workflow
This description of the git/GitHub workflow is written for a person who wants to contribute changes to Tax-Calculator source code. It assumes that you have read the contributor guide and the conventions about naming and placing new policy parameters, have forked the central GitHub Tax-Calculator repository to your GitHub account, and have cloned that forked copy to your local computer.
This document describes the steps you should follow when developing a pull request on your local computer and submitting it to GitHub for review.
After you have forked and cloned the central GitHub Tax-Calculator
repository, you have access to three copies of the repository: the
central repository (called
upstream), the forked repository in your
personal GitHub account (called
origin), and the repository on your
local computer, which is where you will prepare a pull request using
git. git and GitHub are powerful and flexible, so there may be
alternative ways to accomplish the results generated by the following
workflow. But the following is the workflow commonly used by the core
developers of Tax-Calculator.
Steps in the Workflow
It is essential to take each step in the order described here.
We assume that you are at the operating system command prompt in the top-level directory of the Tax-Calculator repository on your local computer. (The top-level directory is the parent directory of the taxcalc subdirectory.)
Make sure you are on the
masterbranch by doing
git branchto confirm the asterisk is marking
master; if not on the
git checkout masterto change the active branch.
Make sure your
masterbranch is synchronized with the
originrepositories by executing
./gitsync(on Mac OS X or Linux) or
Create a new branch that will contain your proposed source-code changes by doing
git checkout -b BNAME(where you type in the name of your branch in place of
In your favorite text editor, revise one or more existing files and save the changes. If you want to add a new file to the Tax-Calculator repository, create and save the new file in your editor and then do
git add FNAME(where you type in the name of your new file in place of
FNAME). If you want to delete an existing file in the Tax-Calculator repository, then do
git rm FNAME(where you type in the name of the file you want to delete in place of
FNAME). If you want to rename an existing file in the Tax-Calculator repository, then do
git mv OLDNAME NEWNAME(where you type in the name of the file you want to rename in place of
OLDNAMEand type in the new name of the file in place of
Next test your proposed source-code changes in two ways: for coding style and for substantive results. Read the documentation on testing procedures for how to conduct these tests on your local computer.
When you have successfully tested your changes, commit the changes to your local repository by doing
git commit -a -m "MESSAGE"(where you type in a short --- no more than about 70 characters --- description of the changes in place of
MESSAGE). Note that it is essential to use the quotation marks around the
MESSAGEbecause it will typically contain spaces.
NOTE THAT SOME PULL REQUESTS CYCLE THROUGH STEPS 4-6 MORE THAN ONCE
When finished with the development of your pull request, submit it to GitHub for review by doing
git push origin BNAME(where you type in the branch name you used in step 3 in place of
Then in your browser go to the central GitHub Tax-Calculator repository and you should see an invitation to create a pull request based on the branch you just pushed to
origin. Accept that invitation, write a meaningful title, add a description of the reason for and nature of your proposed source-code changes, and then click on the "Create" button.
IF ASKED TO MAKE CHANGES, REPEAT STEPS 4-7 ON YOUR DEVELOPMENT BRANCH
To get back on your development branch, do
git checkout BNAME (where
you type in the branch name you used in step 3 in place of
- After your pull request is merged into the
masterbranch, repeat steps 1-2 in order to synchronize your
localrepositories with the new
masterbranch in the
upstreamrepository. You should also delete the now redundant development branch from your local computer by doing
git branch -d BNAME(where you type in the branch name you used in step 3 in place of