Contributor Guide

The purpose of this guide is to get you to the point where you can make improvements to the Tax Calculator and share them with the rest of the team.

We keep track of our Tax Calculator code using Git, but we don’t expect you to be an expert Git user. Where possible, we link to Git and GitHub documentation to help with some of the unfamiliar terminology. Following the next steps will get you up and running and contributing to our model even if you’ve never used anything like Git.

If you have already completed the Setup Python and Setup Git sections, please skip to Workflow.

Setup Python

The Tax Calculator is written in the Python programming language. Download and install the free Anaconda distribution of Python from Continuum Analytics. You must do this even if you already have Python installed on your computer because the Anaconda distribution contains all the additional Python packages that we use to conduct tax calculations (many of which are not included in other Python installations). You can install the Anaconda distribution without having administrative privileges on your computer and the Anaconda distribution will not interfere with any Python installation that came as part of your computer’s operating system.

Setup Git

1. Create a GitHub user account.

2. Install Git on your local machine by following steps 1-4 on Git setup.

3. Tell Git to remember your GitHub password by following steps 1-4 on password setup.

4. Sign in to GitHub and create your own remote repository (repo) of OSPC’s tax calculator by clicking Fork in the upper right corner of the Tax Calculator’s GitHub page. Select your username when asked “Where should we fork this repository?”

5. From your command line, navigate to the directory on your computer where you would like your local repo to live.

6. Create a local repo by entering at the command line the text after the $. [1] This step creates a directory called tax-calculator in the directory that you specified in the prior step.

   $ git clone https://github.com/[github-username]/tax-calculator.git
   

7. From your command line or terminal, navigate to your local tax-calculator directory.

8. Make it easier to push your local work to others and pull others’ work to your local machine by entering at the command line:

   $ cd tax-calculator
   tax-calculator$ git remote add upstream https://github.com/opensourcepolicycenter/tax-calculator.git
   

9. Create a conda environment with all of the necessary packages to execute the source code:

   tax-calculator$ conda env create
   

10. The prior command will create a conda environment called “taxcalc-dev”. Activate this environment as follows:

    tax-calculator$ source activate taxcalc-dev
    

11. To check that everything is working properly, run the following at the command line from the tax-calculator directory.

tax-calculator$ cd taxcalc
tax-calculator/taxcalc$ py.test

If all the tests pass, you’re good to go. If they don’t pass, enter the following updates at the command line and then try running py.test again. If the tests still don’t pass, please contact us.

tax-calculator$ conda update conda
tax-calculator$ conda update anaconda

If you’ve made it this far, you’ve successfully made a remote copy (a fork) of OSPC Tax Calculator repo. That remote repo is hosted on GitHub.com. You’ve also created a local repo (a clone) that lives on your machine and only you can see; you will make your changes to the Tax Calculator by editing the files in the tax-calculator directory on your machine and then submitting those changes to your local repo. As a new contributor, you will push your changes from your local repo to your remote repo when you’re ready to share that work with the team.

Don’t be alarmed if the above paragraph is confusing. The following section introduces some standard Git practices and guides you through the contribution process.

Workflow

The following text describes a typical workflow for the Tax Calculator simulation model. Different workflows may be necessary in some situations, in which case other contributors are here to help.

1. Before you edit the calculator on your machine, make sure you have the latest version of the OSPC Tax Calculator by executing the following four Git commands:

   1. Download all of the content from the main OSPC Tax Calculator repo. Navigate to your local tax-calculator directory and enter the following text at the command line.

      tax-calculator$ git fetch upstream
      

   2. Tell Git to switch to the master branch in your local repo.

      tax-calculator$ git checkout master
      

   3. Update your local master branch to contain the latest content of the OSPC master branch using merge. This step ensures that you are working with the latest version of the Tax Calculator.

      tax-calculator$ git merge upstream/master
      

   4. Push the updated master branch in your local repo to your GitHub repo.

      tax-calculator$ git push
      

2. Create a new branch on your local machine. Think of your branches as a way to organize your projects. If you want to work on this documentation, for example, create a separate branch for that work. If you want to change the maximum child care tax credit in the Tax Calculator, create a different branch for that project.

   tax-calculator$ git checkout -b [new-branch-name]
   

3. See Making changes to your local copy of the Tax Calculator for examples showing you how to do just that.

4. As you make changes, frequently check that your changes do not introduce bugs or degrade the accuracy of the Tax Calculator. To do this, run the following at the command line from inside the tax-calculator/taxcalc directory. If the tests do not pass, try to fix the issue by using the information provided by the error message. If this isn’t possible or doesn’t work, we are here to help.

   tax-calculator/taxcalc$ py.test
   

5. Now you’re ready to commit your changes to your local repo using the code below. The first line of code tells Git to track a file. Use “git status” to find all the files you’ve edited, and “git add” each of the files that you’d like Git to track. As a rule, do not add large files. If you’d like to add a file that is larger than 25 MB, please contact the other contributors and ask how to proceed. The second line of code commits your changes to your local repo and allows you to create a commit message; this should be a short description of your changes.

   Tip: Committing often is a good idea as Git keeps a record of your changes. This means that you can always revert to a previous version of your work if you need to.

   tax-calculator$ git add [filename]
   tax-calculator$ git commit -m "[description-of-your-commit]"
   

6. When you’re ready for other team members to review your code, make your final commit and push your local branch to your remote repo (this repo is also called the origin).

   tax-calculator$ git push origin [new-branch-name]
   

7. Ask other team members to review your changes by directing them to: github.com/[github-username]/Tax-Calculator/[new-branch-name].

8. If this is your first time, wait for feedback and instructions on how to proceed. Most likely, the other contributors will ask you to fetch and merge new changes from upstream/master and then open a pull request.

Simple Usage

For examples of Tax Calculator usage (without changing tax parameter values and without adding a new tax parameter), you can view our code sample notebook: 10 Minutes To TaxCalc.

[1]

The dollar sign is the end of the command prompt on a Mac. If you’re on Windows, this is usually the right angle bracket (>). No matter the symbol, you don’t need to type it (or anything to its left, which shows the current working directory) at the command line before you enter a command; the prompt symbol and preceding characters should already be there.