From 3988317a874d37abbe213d36471a59ae7bfbb971 Mon Sep 17 00:00:00 2001 From: "martin.holmer@gmail.com" Date: Mon, 6 Jan 2025 16:36:17 -0500 Subject: [PATCH] Update contributor guide --- Makefile | 2 +- README.md | 10 +- docs/contributing/RELEASING.md | 85 ++++---------- docs/contributing/contributor_guide.md | 102 ++++++++-------- docs/contributing/dependencies.md | 14 --- docs/contributing/pr_workflow.md | 55 +++++---- docs/contributing/testing.md | 154 +++++++------------------ 7 files changed, 154 insertions(+), 268 deletions(-) delete mode 100644 docs/contributing/dependencies.md diff --git a/Makefile b/Makefile index 2957944b4..1079bf763 100644 --- a/Makefile +++ b/Makefile @@ -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: diff --git a/README.md b/README.md index 55daa6dd4..b15b83bdc 100644 --- a/README.md +++ b/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/). diff --git a/docs/contributing/RELEASING.md b/docs/contributing/RELEASING.md index 15b808796..dd71c5af0 100755 --- a/docs/contributing/RELEASING.md +++ b/docs/contributing/RELEASING.md @@ -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 @@ -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 -``` \ No newline at end of file +--> 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 +``` diff --git a/docs/contributing/contributor_guide.md b/docs/contributing/contributor_guide.md index 8a96959d9..960955f83 100644 --- a/docs/contributing/contributor_guide.md +++ b/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. \ No newline at end of file +You should now read the more detailed {doc}`pr_workflow` document. + +This is the end of the Contributor Guide document. diff --git a/docs/contributing/dependencies.md b/docs/contributing/dependencies.md deleted file mode 100644 index efc71b8d3..000000000 --- a/docs/contributing/dependencies.md +++ /dev/null @@ -1,14 +0,0 @@ -# Dependencies - -## Python - -Tax-Calculator currently runs on Python 3.9, 3.10, 3.11, and 3.12. -We generally support at least the three latest major Python releases. - -Updating the Python version requires modifying the following files: -* `.github/workflows/*.yml` -* `.travis.yml` -* `appveyor.yml` -* `setup.py` -* `docs/usage/starting.md` -* `docs/contributing/dependencies.md` (this file) diff --git a/docs/contributing/pr_workflow.md b/docs/contributing/pr_workflow.md index 2f865b7ba..4dfc82eea 100644 --- a/docs/contributing/pr_workflow.md +++ b/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`). \ No newline at end of file diff --git a/docs/contributing/testing.md b/docs/contributing/testing.md index 9bf00d8ec..3afde3f03 100644 --- a/docs/contributing/testing.md +++ b/docs/contributing/testing.md @@ -4,10 +4,10 @@ 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 +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` @@ -15,126 +15,89 @@ so that you understand where the testing procedures fit into the broader workflow of preparing a pull request that changes Tax-Calculator source code. -Currently there are two phases of testing. +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 with `pycodestyle` (the program formerly known as pep8) +## Testing coding style -The first phase of testing checks the formatting of the Python code -against a PEP8-like standard. Assuming you are in the top-level -directory of the repository, run these tests by doing: -``` -pycodestyle taxcalc -``` +The Tax-Calculator project follows `pycodestyle` and `pylint` +recommended coding style in most cases. -No messages indicate the tests pass. Fix any errors. When you -pass all these PEP8-like tests, proceed to the second phase of testing. +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: -If you are proposing changes in a JSON file, then you should also run -the following test: ``` -pycodestyle --ignore=E501,E121 PATH_TO_JSON_FILE +make cstest ``` -where you replace `PATH_TO_JSON_FILE` with the relative path to the -JSON file you changed. So, for example, if you edited the -`policy_current_law.json` file in the `taxcalc` subdirectory, you -would replace `PATH_TO_JSON_FILE` with -`taxcalc/policy_current_law.json`. + +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. +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. +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 the most recent publicly -available IRS-SOI PUF file and from the Census CPS file for the -corresponding year. If you have acquired from IRS the most recent SOI -PUF file and want to execute the tests that require the `puf.csv` -file, contact the core development team to discuss your options. - -If you have access to the Tax-Calculator `puf.csv` file, you should -have access to the private GitHub repository `taxpuf`, from which -updates of the `puf.csv` are distributed. When you receive a private -email announcing a new version of the `puf.csv` file, be sure to -execute a `conda update ... taxpuf` command (as described in the -`taxpuf` repository's README file) before executing the tests -described below. +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 want to do just a quick test), run the second-phase of testing as -follows at the command prompt in the tax-calculator directory at the -top of the repository directory tree: +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: + ``` -cd taxcalc -pytest -m "not requires_pufcsv and not pre_release" -n4 -cd .. +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. Depending on your computer, the execution time for this -incomplete suite of tests is roughly one minute. The `-n4` option -calls for using as many as four CPU cores for parallel execution of the -tests. If you want sequential execution of the tests (which will -take at least twice as long to execute), simply omit the `-n4` option. +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 -top-level directory: +Tax-Calculator directory: + ``` -cd taxcalc -pytest -m "not pre_release" -n4 -cd .. +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. Depending on your computer, the execution time for this suite -of unit tests is roughly two minutes. The `-n4` option calls for -using as many as four CPU cores for parallel execution of the tests. -If you want sequential execution of the tests (which will take at -least twice as long to execute), simply omit the `-n4` option. +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: + ``` -cd taxcalc -pytest -m pre_release -n4 -cd .. -``` - -But if you execute the pre_release tests well before releasing a new -version of Tax-Calculator, be sure **not** to include the updated -`docs/index.html` file in your commit. After checking that you can -make a `docs/index.html` file that is correct, revert to the old -version of `docs/index.html` by executing this command: -``` -git checkout -- docs/index.html +make pytest-all ``` -Following this procedure will ensure that the documentation is not -updated before the Tax-Calculator release is available. - ## 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 -would be highly desirable 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. +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 +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 @@ -151,34 +114,3 @@ 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. - -## Optional coding style testing with `pylint` - -There is another tool, `pylint`, that warns about deviations from a -broader set coding styles than does `pycodestyle`. The use of -`pylint`, while being the number one recommendation in the [Google -Python Style Guide](https://google.github.io/styleguide/pyguide.html), -is strictly-speaking optional for Tax-Calculator work. But several -important files in the repository are maintained in a way that their -coding style does not generate any `pylint` warnings. You can -determine which files these are by looking for the comments near the -top of the file that begin `# CODING-STYLE CHECKS:`. If there is a -line in these comments that mentions `pylint`, then this file is being -tested with `pylint`. It is highly recommended that, if you are -proposing changes in one these files, you check your work by running -the `pylint` command listed in that file's coding-style comment. - -Make sure you have an up-to-date version of `pylint` installed on your -computer by entering at the operating system command prompt: -``` -pylint --version -``` -If you get a no-such-command error, install `pylint` as follows: -``` -conda install pylint -``` -If you do have `pylint` installed, but the version is before 1.8.4, -then get a more recent version as follows: -``` -conda update pylint -``` \ No newline at end of file