taxcalc 4.3.5__tar.gz → 4.4.1__tar.gz

{taxcalc-4.3.5 → taxcalc-4.4.1}/Makefile

@@ -84,20 +84,17 @@ tctest-jit:
 TOPLEVEL_JSON_FILES := $(shell ls -l ./*json | awk '{print $$9}')
 TAXCALC_JSON_FILES := $(shell ls -l ./taxcalc/*json | awk '{print $$9}')
 TESTS_JSON_FILES := $(shell ls -l ./taxcalc/tests/*json | awk '{print $$9}')
-PYLINT_FILES := $(shell grep -rl --include="*py" disable=locally-disabled .)
-PYLINT_OPTIONS = --disable=locally-disabled --score=no --jobs=4
-RECIPE_FILES := $(shell ls -l ./docs/recipes/recipe*.ipynb | awk '{print $$9}')
-PYLINT_IGNORE = C0103,C0111,E0401,E1120,R0913,R0914,W0401,W0614
-RECIPE_OPTIONS = --disable=$(PYLINT_IGNORE) --score=no --jobs=4
+PYLINT_DISABLE = locally-disabled,duplicate-code,cyclic-import
+PYLINT_OPTIONS = --disable=$(PYLINT_DISABLE) --score=no --jobs=4
+EXCLUDED_PATHS = docs,taxcalc/validation
 
 .PHONY=cstest
 cstest:
-	-pycodestyle .
+	@-pycodestyle --ignore=W503,W504,E712 --exclude=$(EXCLUDED_PATHS) .
 	@-pycodestyle --ignore=E501,E121 $(TOPLEVEL_JSON_FILES)
 	@-pycodestyle --ignore=E501,E121 $(TAXCALC_JSON_FILES)
 	@-pycodestyle --ignore=E501,E121 $(TESTS_JSON_FILES)
-	@-pylint $(PYLINT_OPTIONS) $(PYLINT_FILES)
-	@-pylint $(RECIPE_OPTIONS) $(RECIPE_FILES)
+	@-pylint $(PYLINT_OPTIONS) --ignore-paths=$(EXCLUDED_PATHS) .
 
 define coverage-cleanup
 rm -f .coverage htmlcov/*

{taxcalc-4.3.5 → taxcalc-4.4.1}/PKG-INFO

@@ -1,7 +1,7 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: taxcalc
-Version: 4.3.5
-Summary: taxcalc
+Version: 4.4.1
+Summary: Tax-Calculator
 Home-page: https://github.com/PSLmodels/Tax-Calculator
 Download-URL: https://github.com/PSLmodels/Tax-Calculator
 License: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
@@ -18,13 +18,19 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: setuptools
-Requires-Dist: numpy
-Requires-Dist: pandas
-Requires-Dist: bokeh
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.2
+Requires-Dist: bokeh>=2.4
 Requires-Dist: numba
-Requires-Dist: requests
-Requires-Dist: paramtools>=0.18.3
+Requires-Dist: paramtools>=0.19.0
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: download-url
+Dynamic: home-page
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: summary
 
 | | |
 | --- | --- |
@@ -39,8 +45,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/).

{taxcalc-4.3.5 → taxcalc-4.4.1}/README.md

@@ -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/).

{taxcalc-4.3.5 → taxcalc-4.4.1}/conda.recipe/meta.yaml

@@ -9,10 +9,10 @@ build:
 requirements:
   build:
     - "python>=3.10, <3.13"
-    - "numpy>=1.26,<1.27"
+    - "numpy>=1.26"
     - "pandas>=2.2"
     - "bokeh>=2.4"
-    - "paramtools>=0.18.3"
+    - "paramtools>=0.19.0"
     - numba
     - curl
     - openpyxl
@@ -20,10 +20,10 @@ requirements:
 
   run:
     - "python>=3.10, <3.13"
-    - "numpy>=1.26,<1.27"
+    - "numpy>=1.26"
     - "pandas>=2.2"
     - "bokeh>=2.4"
-    - "paramtools>=0.18.3"
+    - "paramtools>=0.19.0"
     - numba
     - curl
     - openpyxl

{taxcalc-4.3.5 → taxcalc-4.4.1}/docs/about/releases.md

@@ -4,6 +4,36 @@ Go [here](https://github.com/PSLmodels/Tax-Calculator/pulls?q=is%3Apr+is%3Aclose
 for a complete commit history.
 
 
+2025-02-13 Release 4.4.1
+------------------------
+(last merged pull request is
+[#2872](https://github.com/PSLmodels/Tax-Calculator/pull/2872))
+
+**This is a minor enhancement release.**
+
+**API Changes**
+
+**New Features**
+- Cosmetic code changes so that "make cstest" produces no warnings
+- New tests added so that "make coverage" produces 100% code coverage
+- Add c32800 to list of calc variables in records_variables.json file
+[[#2872](https://github.com/PSLmodels/Tax-Calculator/pull/2872) by Martin Holmer]
+
+
+2024-12-19 Release 4.4.0
+------------------------
+(last merged pull request is
+[#2856](https://github.com/PSLmodels/Tax-Calculator/pull/2856))
+
+**This is an enhancement release.**
+
+**API Changes**
+
+**New Features**
+- Make a Policy object's last budget year be flexible
+[[#2856](https://github.com/PSLmodels/Tax-Calculator/pull/2856) by Jason DeBacker with minor assistance from Martin Holmer]
+
+
 2024-12-16 Release 4.3.5
 ------------------------
 (last merged pull request is
@@ -23,8 +53,8 @@ for a complete commit history.
 
 **Bug Fixes**
 - Fix several broken documentation links
-[[#2847](https://github.com/PSLmodels/Tax-Calculator/pull/2847) by Martin Holmer] and
-[[#2849](https://github.com/PSLmodels/Tax-Calculator/pull/2849) by Martin Holmer]
+[[#2847](https://github.com/PSLmodels/Tax-Calculator/pull/2847) by Martin Holmer and
+[#2849](https://github.com/PSLmodels/Tax-Calculator/pull/2849) by Martin Holmer]
 - Remove incorrect use of GrowFactors() in Policy and Parameters classes
 [[#2852](https://github.com/PSLmodels/Tax-Calculator/pull/2852) by Martin Holmer]
 

taxcalc-4.4.1/docs/contributing/RELEASING.md

@@ -0,0 +1,58 @@
+Releasing Tax-Caclculator Packages
+==================================
+
+The following outlines the process for releasing a new `taxcalc` package.
+
+In the top-level Tax-Calculator directory, do the following:
+
+```
+--> run `git switch master`  [to get on master branch]
+
+--> run `./gitsync`  [to ensure master is up-to-date with GitHub version]
+
+--> run `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
+
+--> specify release X.Y.Z in setup.py and taxcalc/__init__.py and docs/index.md
+
+--> run `python update_pcl.py`  [to update policy_current_law.json if needed]
+
+--> run `python ppp.py`  [to update policy_current_law.json if needed]
+
+--> run `python extend_tcja.py > ext.json`  [to update reforms/ext.json]
+
+--> 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 tctest-jit`  [to make sure JIT decorators are not hiding bugs]
+
+--> commit X-Y-Z branch and push to origin
+
+--> open new GitHub pull request using your X-Y-Z branch
+```
+
+Then ask [@jdebacker](https://github.com/jdebacker/) to review and
+merge the pull request and create the package.
+
+
+### Notes on creating package for distribution
+
+```
+--> 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
+```

{taxcalc-4.3.5 → taxcalc-4.4.1}/docs/contributing/contributor_guide.md

@@ -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`.
@@ -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
@@ -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:
@@ -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
@@ -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
@@ -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
       ```
 
@@ -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
@@ -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:
@@ -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
@@ -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.

{taxcalc-4.3.5 → taxcalc-4.4.1}/docs/contributing/pr_workflow.md

@@ -2,12 +2,12 @@ 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.
+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
@@ -18,25 +18,23 @@ 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
+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
+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.)
+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.
+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
@@ -47,26 +45,26 @@ 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
+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
+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.
+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
+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**
@@ -76,22 +74,21 @@ 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
+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 checkout BNAME` (where
+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
+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`).

taxcalc-4.4.1/docs/contributing/testing.md

@@ -0,0 +1,116 @@
+Testing
+=======
+
+This description of Tax-Calculator testing procedures is written for a
+person who wants to contribute changes to Tax-Calculator source code.
+
+It assumes that you have read {doc}`contributor_guide` 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 also assumes that you have read {doc}`pr_workflow`
+so that you understand where the testing procedures fit into
+the broader workflow of preparing a pull request that changes
+Tax-Calculator source code.
+
+There are two phases of testing: testing that the source code
+complies with the Tax-Calculator coding style and testing that
+the source code does not contain bugs.
+
+## Testing coding style
+
+The Tax-Calculator project follows `pycodestyle` and `pylint`
+recommended coding style in most cases.
+
+Check that your changes on a local branch are coding-style compliant
+by running the coding-style test in the top-level Tax-Calculator
+directory as follows:
+
+```
+make cstest
+```
+
+No messages indicate the tests pass.  Fix any warnings.  When you pass
+all these coding-style tests, proceed to the second phase of testing.
+
+## Testing with pytest
+
+There are two variants of this second testing phase depending on
+whether or not you have access to a file called `puf.csv` that
+contains a representative sample of tax filing units derived from the
+IRS-SOI PUF data.
+
+A brief description of the `puf.csv` file is followed by instructions
+on how to run the two variants of the second-phase tests.
+
+The Tax-Calculator `puf.csv` file has been constructed by the core
+development team by merging information from a publicly available
+IRS-SOI PUF file for 2011 and from the Census CPS file for the
+corresponding year.  If you have acquired from IRS the 2011 SOI PUF
+file and want to execute the tests that require the `puf.csv` file,
+contact the core development team to discuss your options.
+
+**NO PUF.CSV**: If you do not have access to the `puf.csv` file (or if
+you just want to do a quick test), run the second-phase of testing as
+follows at the command prompt in the Tax-Calculator directory:
+
+```
+make pytest-cps
+```
+
+This will start executing a pytest suite containing hundreds of tests,
+but will skip the tests that require the `puf.csv` file as input and
+the tests that are executed only just before a new release is being
+prepared.
+
+**HAVE PUF.CSV**: If you do have access to the `puf.csv` file, copy it
+into the Tax-Calculator directory at the top of the repository
+directory tree (but **never** add it to your repository) and run the
+second-phase of testing as follows at the command prompt in the
+Tax-Calculator directory:
+
+```
+make pytest
+```
+
+This will start executing a pytest suite containing hundreds of tests,
+including the tests that require the `puf.csv` file as input but
+excluding the tests that are executed only just before a new release
+is being prepared.
+
+Just before releasing a new version of Tax-Calculator or just after
+adding a new parameter to `policy_current_law.json`, you should also
+execute the pre-release tests using this command:
+
+```
+make pytest-all
+```
+
+## Interpreting test results
+
+If you are adding an enhancement that expands the capabilities of the
+Tax-Calculator, then all the tests you can run should pass before you
+submit a pull request containing the enhancement.  In addition, it
+essential to add a test to the pytest suite, which is located in the
+`taxcalc/tests` directory, that somehow checks that your enhancement
+is working as you expect it to work.
+
+On the other hand, if you think you have found a bug in the existing
+Tax-Calculator source code, the first thing to do is add a test to the
+pytest suite that demonstrates how the source code produces an
+incorrect result (that is, the test fails because the result is
+incorrect).  Then change the source code to fix the bug and
+demonstrate that the newly-added test, which used to fail, now passes.
+
+## Updating test results
+
+After an enhancement or bug fix, you may be convinced that the new and
+different second-phase test results are, in fact, correct.  How do you
+eliminate the test failures?  For all but the few tests that require
+the `puf.csv` file or the `cps.csv` file as input, simply edit the
+appropriate `taxcalc/tests/test_*.py` file so that the test passes
+when you rerun pytest.  If there are failures for the tests that write
+results files, read the test error message for instructions about how
+to update the test results.