Skip to content

Commit

Permalink
Merge pull request #2861 from martinholmer/contributor-guide
Browse files Browse the repository at this point in the history 
Update contributor guide
  • Loading branch information
@martinholmer
martinholmer authored Jan 6, 2025
2 parents 2468193 + 3988317 commit 74ab0a9
Show file tree
Hide file tree
Showing 7 changed files with 154 additions and 268 deletions.
2 changes: 1 addition & 1 deletion Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ TAXCALC_JSON_FILES := $(shell ls -l ./taxcalc/*json | awk '{print $$9}')
TESTS_JSON_FILES := $(shell ls -l ./taxcalc/tests/*json | awk '{print $$9}')
PYLINT_DISABLE = locally-disabled,duplicate-code,cyclic-import
PYLINT_OPTIONS = --disable=$(PYLINT_DISABLE) --score=no --jobs=4
EXCLUDED_PATHS = taxcalc/validation,docs/guide
EXCLUDED_PATHS = docs,taxcalc/validation

.PHONY=cstest
cstest:
Expand Down
10 changes: 8 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,14 @@ Tax-Calculator
Tax-Calculator is an open-source microsimulation model for static
analysis of USA federal income and payroll taxes.

We are seeking contributors and maintainers. If you are interested in joining the project as a contributor or maintainer,
open a new [issue](https://github.com/PSLmodels/Tax-Calculator/issues) and ping [@MattHJensen](https://github.com/MattHJensen/) or [@jdebacker](https://github.com/jdebacker/) -- or just jump right in.
We are seeking contributors and maintainers. If you are interested in
joining the project as a contributor or maintainer, open a new
[issue](https://github.com/PSLmodels/Tax-Calculator/issues) and ping
[@MattHJensen](https://github.com/MattHJensen/) or
[@jdebacker](https://github.com/jdebacker/) -- or just jump right in.
The [contributor
guide](https://taxcalc.pslmodels.org/contributing/contributor_guide.html)
explains the workflow involved in contributing model enhancements.

Complete documentation is available
[here](https://PSLmodels.github.io/Tax-Calculator/).
85 changes: 25 additions & 60 deletions docs/contributing/RELEASING.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,21 @@
Releasing Tax-Caclculator Packages
==================================

The following outlines the process to release Tax-Calculator Packages
on Conda-Forge and creating a new branch to fix a bug in a previous
release.
The following outlines the process for releasing a new Tax-Calculator package.

Create new `taxcalc` package
============================

In the top-level Tax-Calculator directory, do the following:

Create new `taxcalc` packages
=============================
```
--> merge master branch into X-Y-Z branch
--> run `git switch master` [to get on master branch]
--> run `./gitsync` [to ensure master is up-to-date with GitHub version]
--> make clean [to remove any local taxcalc package]
--> run `git checkout -b X-Y-Z` [to create X-Y-Z (e.g., `4-4-1`) branch]
--> on branch X-Y-Z, edit docs/about/releases.md to finalize X.Y.Z info
Expand All @@ -20,73 +27,31 @@ Create new `taxcalc` packages
--> run `python extend_tcja.py > ext.json` [to update reforms/ext.json]
--> run `make tctest-jit` [to make sure JIT decorators are not hiding bugs]
--> run `make cstest` [to make confirm project coding style is being followed]
--> run `make pytest-all` [or `pytest -m pre_release -n4` in taxcalc subdir]
--> run `make package` [to make local taxcalc package available]
--> cd taxcalc/validation ; ./tests_35.sh ; .fix. ; cd ../..
--> make clean [to remove taxcalc package]
--> run `make tctest-jit` [to make sure JIT decorators are not hiding bugs]
--> commit X-Y-Z branch and push to origin
--> merge X-Y-Z branch into master branch on GitHub
--> on local master branch, ./gitsync
--> create release X.Y.Z on GitHub using master branch
--> Create new package on Conda-Forge for release X.Y.Z
--> open a PR to github.com/conda-forge/taxcalc-feedstock where you change the `recipe/meta.yaml` file by updating (1) the version number to X.Y.Z and (2) the checksum to reflect the checksum for the tarball for release X.Y.Z in the Tax-Calculator GitHub repo
====> ADD NEW DEPENDENCY OR UPDATE MINIMUM REQUIRED VERSION <====
--> open new GitHub pull request using your X-Y-Z branch
--> add or update `run` list in `requirements` section of `conda.recipe/meta.yaml`
--> add or update package in `environment.yaml`
(this may have already been done in the PR that added or updated the
dependency.)
--> update `dev_pkgs` list in `test_4package.py:test_for_consistency` and make sure
the updated test passes
====> CREATE NEW BEHRESP PACKAGES (if necessary) <====
--> create Behavioral-Responses packages
====> NOTIFY OTHER DEVELOPERS <====
--> email Tax-Calculator user list about the new release and packages
--> ask [@jdebacker](https://github.com/jdebacker/) to merge and create package
```


Creating a new branch to fix a bug in an old release
====================================================

Useful when tip of master branch includes major changes since old release.

EXAMPLE: fix bug in release 1.4.0 and then release 1.4.1
Notes for person actually creating package
==========================================

```
$ cd ~/work/PSL/Tax-Calculator
$ git checkout master
$ git checkout -b 1-4-1 1.4.0
--> fix bug on branch 1-4-1, test, commit bug fix
$ git push upstream 1-4-1
--> merge X-Y-Z branch into master branch on GitHub
--> create release 1.4.1 using GitHub releases GUI citing branch 1-4-1
--> on local master branch, ./gitsync
--> then in order to merge bug-fix into master branch and future releases
beginning with 1.5.0, do the following:
--> create release X.Y.Z on GitHub using master branch
$ git checkout master
--> create new package on Conda-Forge for release X.Y.Z
$ git merge 1-4-1
```
--> open a PR to github.com/conda-forge/taxcalc-feedstock where you change the `recipe/meta.yaml` file by updating (1) the version number to X.Y.Z and (2) the checksum to reflect the checksum for the tarball for release X.Y.Z in the Tax-Calculator GitHub repo
```
102 changes: 51 additions & 51 deletions docs/contributing/contributor_guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ 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
make improvements to Tax-Calculator and share them with the rest
of the development team as a GitHub pull request.
This document assumes that you have read {doc}`../usage/starting` and
{doc}`../recipes/index`.
Expand All @@ -14,50 +14,52 @@ paragraph **before** preparing a pull request.
(a) Modify {doc}`../recipes/recipe06` to
analyze the kind of tax reform you want to add to the list of reforms
that can be analyzed parametricly by Tax-Calculator.
(b) Raise a Tax-Calculator issue in which you show your modified recipe 6 that
simulates the reform and provide some numerical results that
illustrate the effects of the reform.
In the course of the conversation about your issue, you may be asked to prepare a pull request that would allow this reform to be analyzed using new policy parameters and associated logic.
If so, follow the directions below when preparing that pull request.
(b) Raise a Tax-Calculator issue in which you show your modified
recipe 6 that simulates the reform and provide some numerical results
that illustrate the effects of the reform.
In the course of the conversation about your issue, you may be asked
to prepare a pull request that would allow this reform to be analyzed
using new policy parameters and associated logic. If so, follow the
directions below when preparing that pull request.

We keep track of Tax-Calculator source code using the [Git version
control system](https://git-scm.com/) via
[GitHub](https://help.github.com/articles/github-glossary/#git). We
don't expect you to be an expert Git user.
Where possible, we link toGit and GitHub documentation to help with some of the unfamiliar terminology (often from this [glossary of GitHub
terms](https://help.github.com/articles/github-glossary/).
Following the next steps will get you up and running and contributing to
control system and
GitHub](https://www.w3schools.com/git/git_intro.asp?remote=github).
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 (often from this [glossary of GitHub
terms](https://help.github.com/articles/github-glossary/)). Following
the next steps will get you up and running and contributing to
Tax-Calculator even if you've never used anything like Git and GitHub.
But if you are unfamiliar with the concept of version control, you
should read an introductory tutorial online.
A good tutorial can be found
should read an introductory tutorial online. A good tutorial can be
found
[here](https://homes.cs.washington.edu/~mernst/advice/version-control.html).

If you have already completed the [Setup Python](#setup-python) and
[Setup Git](#setup-Git) sections, please skip to [Workflow](#workflow).
If you have already completed the following Setup Python and Setup Git
sections, please skip to [Workflow](#workflow).


## Setup Python

Follow the [getting started instructions](https://PSLmodels.github.io/Tax-Calculator/tc_starting.html),
but be sure to skip step 2, because the installation of the `taxcalc`
package will interfere with the testing of changes in the source code.
Follow the [getting started
instructions](https://taxcalc.pslmodels.org/usage/starting.html).

If you are new to or have limited experience with Python, you should
read some introductory tutorials available online. One such tutorial
is [Quantitative Economics with
Python](https://lectures.quantecon.org/py/).
read some introductory tutorials available online. One such
interactive tutorial is the [W3 Schools' Python
Introduction](https://www.w3schools.com/python/python_intro.asp).


## Setup Git

1. Create a free GitHub user account from the [GitHub home
page](https://github.com/).
page](https://github.com).

2. Install Git on your local computer by following steps 1-4
2. Install Git on your local computer by following the steps
[here](https://help.github.com/articles/set-up-git/).

3. Tell Git to remember your GitHub password by following steps 1-4
3. Tell Git to remember your GitHub password by following the steps
[here](https://help.github.com/articles/caching-your-github-password-in-git/).

4. Sign in to GitHub and create your own
Expand Down Expand Up @@ -97,21 +99,17 @@ page](https://github.com/).
9. Create a conda environment with all of the necessary packages to
execute Tax-Calculator source code in the Tax-Calculator directory:
```
conda env create
conda create --name taxcalc-dev
```

10. The prior command will create a conda environment called `taxcalc-dev`.
Activate this environment as follows if working on Mac or Linux:
Activate this environment as follows:
```
source activate taxcalc-dev
```
If you are working on Windows, use the following from the command line:
```
activate taxcalc-dev
conda activate taxcalc-dev
```
Important Note: never conda install the taxcalc package in the
taxcalc-dev environment because the taxcalc source code and the
installed package will conflict.
installed package may be in conflict.
11. To check that everything is working properly, run the following at
the command line in the Tax-Calculator directory:
Expand All @@ -136,7 +134,7 @@ page](https://github.com/).
If you've made it this far, you've successfully made a remote copy (a
fork) of central Tax-Calculator repo. That remote repo is hosted on
GitHub.com. You've also created a local repo --- a
GitHub. You've also created a local repo --- a
[clone](https://help.github.com/articles/github-glossary/#clone) ---
that lives on your computer and only you can see; you will make your
changes to the Tax-Calculator by editing the files in the
Expand Down Expand Up @@ -166,7 +164,7 @@ situations, in which case other contributors are here to help.
Navigate to your local Tax-Calculator directory and enter the
following text at the command line:
```
git checkout master
git switch master
```
b. Download all of the content from the central Tax-Calculator repo
Expand Down Expand Up @@ -198,13 +196,13 @@ situations, in which case other contributors are here to help.
simply execute substeps `a` and `e`. If you are working on Mac
or Linux, execute these commands in the Tax-Calculator directory:
```
git checkout master
git switch master
./gitsync
```
If you are working on Windows, execute these commands in the
Tax-Calculator directory:
```
git checkout master
git switch master
gitsync
```
Expand All @@ -224,17 +222,17 @@ situations, in which case other contributors are here to help.
sure to read about the Tax-Calculator {doc}`param_naming`.
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 commands from the command line from inside
the Tax-Calculator/taxcalc directory::
violate Tax-Calculator coding style, introduce bugs, or degrade the
accuracy of Tax-Calculator. To do this, run the following commands
from the command line in the Tax-Calculator directory:
```
pycodestyle .
pytest -m "not requires_pufcsv and not pre_release" -n4
make cstest
make pytest-cps
```
Consult {doc}`testing` for more details.
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
If the tests do not pass, try to fix the problem by using the
information provided by the error message. If this isn't possible
or doesn't work, we are here to help.
5. Now you're ready to
Expand Down Expand Up @@ -278,9 +276,9 @@ situations, in which case other contributors are here to help.
```
You may need to resolve conflicts that arise when another
contributor changed the same section of code that you are
changing. Feel free to ask other contributors for guidance
if this happens to you. If you do need to fix a merge
conflict, run the tests (step 4) again fixing.
changing. Feel free to ask other contributors for guidance
if this happens to you. If you do need to fix a merge
conflict, run the tests (step 4) again after fixing.
7. When you are ready for other team members to review your code, make
your final commit and push your local branch to your remote repo:
Expand All @@ -289,9 +287,9 @@ situations, in which case other contributors are here to help.
```
8. From the [central GitHub Tax-Calculator
page](https://github.com/PSLmodels/Tax-Calculator), open a
[pull request](https://help.github.com/articles/creating-a-pull-request/#creating-the-pull-request)
containing the changes in your local branch.
page](https://github.com/PSLmodels/Tax-Calculator), open a [pull
request](https://help.github.com/articles/creating-a-pull-request/#creating-the-pull-request)
containing the changes in your local branch.
9. When you open a GitHub pull request, a code coverage report will be
automatically generated. If your branch adds new code that is not
Expand All @@ -306,4 +304,6 @@ branch, commit them (step 6), and push them to your remote repo (step
7), and these changes will be automatically incorporated into your
pull request.
You should now read the more detailed {doc}`pr_workflow` document.
You should now read the more detailed {doc}`pr_workflow` document.
This is the end of the Contributor Guide document.
14 changes: 0 additions & 14 deletions docs/contributing/dependencies.md
View file

This file was deleted.

Loading

0 comments on commit 74ab0a9

Please sign in to comment.