Pull request workflow

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 and Policy parameter naming and placing conventions, 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.)

  1. Make sure you are on the master branch by doing git branch to confirm the asterisk is marking master; if not on the master branch, do git checkout master to change the active branch.

  2. Make sure your master branch is synchronized with the upstream and origin repositories by executing ./gitsync (on Mac OS X or Linux) or gitsync (on Windows).

  3. 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 BNAME).

  4. 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 OLDNAME and type in the new name of the file in place of NEWNAME).

  5. Next test your proposed source-code changes in two ways: for coding style and for substantive results. Read Testing for how to conduct these tests on your local computer.

  6. 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 MESSAGE because it will typically contain spaces.

NOTE THAT SOME PULL REQUESTS CYCLE THROUGH STEPS 4-6 MORE THAN ONCE

  1. 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 BNAME).

  2. 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 BNAME).

  1. After your pull request is merged into the upstream master branch, repeat steps 1-2 in order to synchronize your origin and local repositories with the new master branch in the upstream repository. 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 BNAME).