From 89f9d6f2735cd66a5a3a74292b820fad951d9fb8 Mon Sep 17 00:00:00 2001 From: Bodi Yang Date: Tue, 9 Apr 2024 14:01:43 -0400 Subject: [PATCH] edit --- docs/_toc.yml | 2 +- docs/contributing/RELEASING.md | 10 +-- docs/contributing/contributor_guide.md | 86 +++++++++++++------------- docs/contributing/dependencies.md | 2 +- docs/contributing/pr_workflow.md | 22 +++---- docs/contributing/testing.md | 32 +++++----- 6 files changed, 77 insertions(+), 77 deletions(-) diff --git a/docs/_toc.yml b/docs/_toc.yml index 0c6891b..4c4e4e7 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -41,6 +41,6 @@ parts: - file: api/policy - file: api/records - file: api/taxcalcio -- caption: Tax-Calculator use cases +- caption: Model use cases chapters: - file: use_cases diff --git a/docs/contributing/RELEASING.md b/docs/contributing/RELEASING.md index 30ea74d..ac25f48 100755 --- a/docs/contributing/RELEASING.md +++ b/docs/contributing/RELEASING.md @@ -1,9 +1,9 @@ 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 to release Taxcalc-Payroll Packages on Conda-Forge and creating a new branch to fix a bug in a previous release. -Create new `taxcalc` packages +Create new `taxcalcpayroll` packages =========================== ``` @@ -34,7 +34,7 @@ Create new `taxcalc` packages --> 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 + --> 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 Taxcalc-Payroll GitHub repo ====> ADD NEW DEPENDENCY OR UPDATE MINIMUM REQUIRED VERSION <==== @@ -53,7 +53,7 @@ Create new `taxcalc` packages ====> NOTIFY OTHER DEVELOPERS <==== ---> email Tax-Calculator user list about the new release and packages +--> email Taxcalc-Payroll user list about the new release and packages ``` @@ -65,7 +65,7 @@ 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 ``` -$ cd ~/work/PSL/Tax-Calculator +$ cd ~/work/user_name/Taxcalc-Payroll $ git checkout master diff --git a/docs/contributing/contributor_guide.md b/docs/contributing/contributor_guide.md index 8a96959..1a269d6 100644 --- a/docs/contributing/contributor_guide.md +++ b/docs/contributing/contributor_guide.md @@ -2,32 +2,32 @@ 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 the Taxcalc-Payroll 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`. -If the objective of your Tax-Calculator improvement is to add the +If the objective of your Taxcalc-Payroll improvement is to add the ability to analyze a tax reform that cannot be analyzed using existing policy parameters, then you need to follow the steps described in this 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 +that can be analyzed parametricly by Taxcalc-Payroll. +(b) Raise a Taxcalc-Payroll 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 +We keep track of Taxcalc-Payroll 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 -Tax-Calculator even if you've never used anything like Git and GitHub. +Taxcalc-Payroll 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 @@ -40,7 +40,7 @@ If you have already completed the [Setup Python](#setup-python) and ## 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` +but be sure to skip step 2, because the installation of the `taxcalcpayroll` package will interfere with the testing of changes in the source code. If you are new to or have limited experience with Python, you should @@ -63,10 +63,10 @@ page](https://github.com/). 4. Sign in to GitHub and create your own [remote](https://help.github.com/articles/github-glossary/#remote) [repository](https://help.github.com/articles/github-glossary/#repository) - (or "repo" for short) of Tax-Calculator by clicking on + (or "repo" for short) of Taxcalc-Payroll by clicking on [Fork](https://help.github.com/articles/github-glossary/#fork) in - the upper right corner of the [Tax-Calculator GitHub - page](https://github.com/PSLmodels/Tax-Calculator). Select your + the upper right corner of the [Taxcalc-Payroll GitHub + page](https://github.com/bodiyang/Taxcalc-Payroll). Select your username when asked "Where should we fork this repository?" 5. From your command line, navigate to the directory on your computer @@ -74,14 +74,14 @@ page](https://github.com/). 6. Create a local repo by entering at the command line the text after the `$` character on Mac and Linux (or the `>` character on Windows). - This step creates a directory called Tax-Calculator in + This step creates a directory called Taxcalc-Payroll in the directory that you specified in the prior step: ``` - git clone https://github.com/[github-username]/Tax-Calculator.git + git clone https://github.com/[github-username]/Taxcalc-Payroll.git ``` 7. From your command line or terminal, navigate to your local - Tax-Calculator directory. + Taxcalc-Payroll directory. 8. Make it easier to [push](https://help.github.com/articles/github-glossary/#push) your @@ -90,36 +90,36 @@ page](https://github.com/). others' work to your local computer by entering at the command line: ``` - cd Tax-Calculator - git remote add upstream https://github.com/PSLmodels/Tax-Calculator.git + cd Taxcalc-Payroll + git remote add upstream https://github.com/bodiyang/Taxcalc-Payroll.git ``` 9. Create a conda environment with all of the necessary packages to - execute Tax-Calculator source code in the Tax-Calculator directory: + execute Taxcalc-Payroll source code in the Taxcalc-Payroll directory: ``` conda env create ``` -10. The prior command will create a conda environment called `taxcalc-dev`. +10. The prior command will create a conda environment called `taxcalcpayroll-dev`. Activate this environment as follows if working on Mac or Linux: ``` - source activate taxcalc-dev + source activate taxcalcpayroll-dev ``` If you are working on Windows, use the following from the command line: ``` - activate taxcalc-dev + activate taxcalcpayroll-dev ``` - Important Note: never conda install the taxcalc package in the - taxcalc-dev environment because the taxcalc source code and the + Important Note: never conda install the taxcalcpayroll package in the + taxcalcpayroll-dev environment because the taxcalcpayroll source code and the installed package will conflict. 11. To check that everything is working properly, run the following at - the command line in the Tax-Calculator directory: + the command line in the Taxcalc-Payroll directory: ``` - cd taxcalc + cd taxcalcpayroll pytest -m "not requires_pufcsv and not pre_release" -n4 ``` - If you do have a copy of the `puf.csv` file used by Tax-Calculator, + If you do have a copy of the `puf.csv` file used by Taxcalc-Payroll, then on the second line above omit the `not requires_pufcsv and` expression so as to execute `pytest -m "not pre_release" -n4`. @@ -131,16 +131,16 @@ page](https://github.com/). conda env update ``` - For more detail on Tax-Calculator testing procedures, read {doc}`testing`. + For more detail on Taxcalc-Payroll testing procedures, read {doc}`testing`. If the tests still don't pass, please contact us. 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 +fork) of central Taxcalc-Payroll repo. That remote repo is hosted on GitHub.com. 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 -Tax-Calculator directory on your computer and then submitting those +changes to the Taxcalc-Payroll by editing the files in the +Taxcalc-Payroll directory on your computer 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. @@ -153,23 +153,23 @@ the contribution process. ## Workflow The following text describes a typical workflow for changing -Tax-Calculator. Different workflows may be necessary in some +Taxcalc-Payroll. Different workflows may be necessary in some situations, in which case other contributors are here to help. -1. Before you edit the Tax-Calculator source code on your computer, - make sure you have the latest version of the central Tax-Calculator +1. Before you edit the Taxcalc-Payroll source code on your computer, + make sure you have the latest version of the central Taxcalc-Payroll repository by executing the **four** Git commands listed in substeps `a-d` (or alternatively by executing just substeps `a` and `e`): a. Tell Git to switch to the master branch in your local repo. - Navigate to your local Tax-Calculator directory and enter the + Navigate to your local Taxcalc-Payroll directory and enter the following text at the command line: ``` git checkout master ``` - b. Download all of the content from the central Tax-Calculator repo + b. Download all of the content from the central Taxcalc-Payroll repo using the Git [fetch](https://help.github.com/articles/github-glossary/#fetch) command: @@ -181,7 +181,7 @@ situations, in which case other contributors are here to help. the central master branch using the Git [merge](https://help.github.com/articles/github-glossary/#merge) command. This step ensures that you are working with the latest - version of the Tax-Calculator on your computer: + version of the Taxcalc-Payroll on your computer: ``` git merge upstream/master ``` @@ -196,13 +196,13 @@ situations, in which case other contributors are here to help. e. As an alternative to executing substeps `a-d`, you can simply execute substeps `a` and `e`. If you are working on Mac - or Linux, execute these commands in the Tax-Calculator directory: + or Linux, execute these commands in the Taxcalc-Payroll directory: ``` git checkout master ./gitsync ``` If you are working on Windows, execute these commands in the - Tax-Calculator directory: + Taxcalc-Payroll directory: ``` git checkout master gitsync @@ -210,23 +210,23 @@ situations, in which case other contributors are here to help. 2. Create a new [branch](https://help.github.com/articles/github-glossary/#branch) - on your local computer in the Tax-Calculator directory. Think of + on your local computer in the Taxcalc-Payroll directory. 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 + credit in the Taxcalc-Payroll, create a different branch for that project: ``` git checkout -b [new-branch-name] ``` 3. If your changes involve creating a new tax policy parameter, be - sure to read about the Tax-Calculator {doc}`param_naming`. + sure to read about the Taxcalc-Payroll {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. + introduce bugs or degrade the accuracy of the Taxcalc-Payroll. To do this, run the following commands from the command line from inside - the Tax-Calculator/taxcalc directory:: + the Taxcalc-Payroll/taxcalcpayroll directory:: ``` pycodestyle . pytest -m "not requires_pufcsv and not pre_release" -n4 @@ -288,8 +288,8 @@ situations, in which case other contributors are here to help. git push origin [new-branch-name] ``` -8. From the [central GitHub Tax-Calculator -page](https://github.com/PSLmodels/Tax-Calculator), open a +8. From the [central GitHub Taxcalc-Payroll +page](https://github.com/bodiyang/Taxcalc-Payroll), open a [pull request](https://help.github.com/articles/creating-a-pull-request/#creating-the-pull-request) containing the changes in your local branch. diff --git a/docs/contributing/dependencies.md b/docs/contributing/dependencies.md index c975037..f289e01 100644 --- a/docs/contributing/dependencies.md +++ b/docs/contributing/dependencies.md @@ -2,7 +2,7 @@ ## Python -Tax-Calculator currently runs on Python 3.7, 3.8, and 3.9. +Taxcalc-Payroll currently runs on Python 3.7, 3.8, and 3.9. We generally support the three latest major Python releases. Updating the Python version requires modifying the following files: diff --git a/docs/contributing/pr_workflow.md b/docs/contributing/pr_workflow.md index 2f865b7..eeec64a 100644 --- a/docs/contributing/pr_workflow.md +++ b/docs/contributing/pr_workflow.md @@ -2,18 +2,18 @@ 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. +who wants to contribute changes to Taxcalc-Payroll 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) +have forked the [central GitHub Taxcalc-Payroll +repository](https://github.com/bodiyang/Taxcalc-Payroll) 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 +After you have forked and cloned the central GitHub Taxcalc-Payroll 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 @@ -23,14 +23,14 @@ 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. +developers of Taxcalc-Payroll. ## 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 +the top-level directory of the Taxcalc-Payroll repository on your local computer. (The top-level directory is the parent directory of the taxcalc subdirectory.) @@ -48,13 +48,13 @@ 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 +If you want to add a new file to the Taxcalc-Payroll 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 +Taxcalc-Payroll 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 Taxcalc-Payroll 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`). @@ -75,8 +75,8 @@ will typically contain spaces. 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) +8. Then in your browser go to the [central GitHub Taxcalc-Payroll +repository](https://github.com/bodiyang/Taxcalc-Payroll) 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 diff --git a/docs/contributing/testing.md b/docs/contributing/testing.md index 9bf00d8..406e3ae 100644 --- a/docs/contributing/testing.md +++ b/docs/contributing/testing.md @@ -1,19 +1,19 @@ Testing ======= -This description of Tax-Calculator testing procedures is written for a -person who wants to contribute changes to Tax-Calculator source code. +This description of Taxcalc-Payroll testing procedures is written for a +person who wants to contribute changes to Taxcalc-Payroll 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) +have forked the [central GitHub Taxcalc-Payroll +repository](https://github.com/bodiyang/Taxcalc-Payroll) 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. +Taxcalc-Payroll source code. Currently there are two phases of testing. @@ -50,14 +50,14 @@ 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 +The Taxcalc-Payroll `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 +If you have access to the Taxcalc-Payroll `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 @@ -67,7 +67,7 @@ described below. **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 +follows at the command prompt in the Taxcalc-Payroll directory at the top of the repository directory tree: ``` cd taxcalc @@ -85,7 +85,7 @@ tests. If you want sequential execution of the tests (which will take at least twice as long to execute), simply omit the `-n4` option. **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 +into the Taxcalc-Payroll 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: @@ -104,7 +104,7 @@ 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. -Just before releasing a new version of Tax-Calculator or just after +Just before releasing a new version of Taxcalc-Payroll or just after adding a new parameter to `policy_current_law.json`, you should also execute the pre-release tests using this command: ``` @@ -114,7 +114,7 @@ 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 +version of Taxcalc-Payroll, 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: @@ -123,19 +123,19 @@ git checkout -- docs/index.html ``` Following this procedure will ensure that the documentation is not -updated before the Tax-Calculator release is available. +updated before the Taxcalc-Payroll 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 +Taxcalc-Payroll, 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 +located in the `taxcalcpayroll/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 -Tax-Calculator source code, the first thing to do is add a test to the +Taxcalc-Payroll 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 @@ -158,7 +158,7 @@ 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 +is strictly-speaking optional for Taxcalc-Payroll 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