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 {doc}`contributor_guide` and and
{doc}`param_naming`, have forked the [central GitHub Tax-Calculator
repository](https://github.com/PSLmodels/Tax-Calculator) 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 switch 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 {doc}`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**

7. 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`).

8. Then in your browser go to the [central GitHub Tax-Calculator
repository](https://github.com/PSLmodels/Tax-Calculator) 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 switch BNAME` (where
you type in the branch name you used in step 3 in place of `BNAME`).

9. 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`).