Joining the ETI-Tax-Analyzer Development Team

We explain how to do this in two sections:

• Installing the Required Development Environment

• Model Development Workflow

---

Installing the Required Development Environment

Using the ETI-Tax-Analyzer in easy on Linux, Mac, and Windows computers. However, the environment needed to do model development work is more extensive. In this section, we describe how to install the required development environment on each of those kinds of computers. Do the computer-specific things first, then do the things for all computers.

• Linux computers. There are no preliminary things to do, so proceed to the all-computers things-to-do list.

• Mac computers. There is only one thing to do: install the Xcode command-line tools (in order to get the GNU make utility, for example). The easiest way to do this is by using the xcode-select command, first using the --help option and then the --install option. After doing that, proceed to the all-computers things-to-do list.

• Windows computers. The native Windows operating system has almost none of what it needed for the development environment. Given that situation, the best strategy is to run Linux on your Windows 10 computer using Microsoft's [Windows Subsystem for Linux]110 running the free Ubuntu Linux distribution. Once that is done, proceed to the all-computers things-to-do list while you are running Ubuntu under WSL. Note that Microsoft makes WSL available at no charge; it is an optional extension to Windows 10.

All computers. Once this basic development environment has been setup, take the following steps (ignoring Fossil warnings about unversioned content):

1. Activate the tafe conda environment

2. Install Fossil (version 2.17 or higher) in your /usr/local/bin directory

3. Clone the central Tax-Analyzer-Framework repository to your computer using these commands:
   mkdir ~/Fossils
cd ~/Fossils
fossil clone https://chiselapp.com/user/PSG/repository/Tax-Analyzer-Framework Tax-Analyzer-Framework.fossil

4. Install the Tax-Analyzer-Framework package using these commands:
   mkdir ~/Tax-Analyzer-Framework
cd ~/Tax-Analyzer-Framework
fossil open cd ~/Fossils/Tax-Analyzer-Framework.fossil
make package

5. Clone the central ETI-Tax-Analyzer Fossil repository to your computer using these commands:
   cd ~/Fossils
fossil clone https://chiselapp.com/user/WBG/repository/ETI-Tax-Analyzer ETI-Tax-Analyzer.fossil

6. Open a source-code tree from the local repository using these commands:
   mkdir ~/ETI-Tax-Analyzer
cd ~/ETI-Tax-Analyzer
fossil open ~/Fossils/ETI-Tax-Analyzer.fossil

7. Copy the private all.csv model input data file to the ~/ETI-Tax-Analyzer/etitaxanalyzer directory

Testing the Development Environment. Once the development environment has been installed, we can test that all is working as expected by trying the following commands in the ~/ETI-Tax-Analyzer directory:

• make help
  should show all the Makefile targets

• make alltests
  should execute all the tests without reporting any warnings or errors

• make coverage
  should produce in your default web browser a page that shows the code coverage of the pytest suite of tests

• make package
  command should create the etitaxanalyzer package

• etigui
  should start the ETI-Tax-Analyzer graphical user interface (GUI) after creating the etitaxanalyzer package

Model Development Workflow

All members of the development team follow a core set of working rules when they are making changes to the model. The details of their working style may vary, but each team member's working style follows these core working rules.

The core working rules are as follows:

1. Use the Fossil GUI often to see what the team is doing in relation to what you are doing on the Timeline page.

2. In a directory containing checked-out code, use the following commands to see the status of the code:
   fossil bran     [to see which branch is checked out]
   fossil chan     [to see which files have been changed]
   fossil extr     [to see which files are not under version control]
   fossil diff     [to see line-by-line file changes on the command line]
   fossil diff --by     [to see side-by-side file changes in your default web browser]

3. Before beginning to work on a change to the model, be sure your local repositories are up to date. Do this by using the following commands:
   cd ~/Tax-Analyzer-Framework
fossil checkout trunk     [only if not already on trunk branch]
   fossil update
cd ~/ETI-Tax-Analyzer
fossil checkout trunk     [only if not already on trunk branch]
   fossil update

4. When making a change to the model — either a model enhancement or a bug fix or a documentation change — always commit the changes on a branch. If you don't yet want to share your work with other team members, make the branch private. So, the first commit on a private branch would use this command:
   fossil commit --private --branch the-branch-name -m "Commit message here."
   The first commit to a public branch would be the same command except the --private option is omitted.

5. After finishing the change (by committing once or several times on the branch), make sure the change passes all the tests for code style and code logic. Do that by using this command:
   make alltests
   If there are pycodestyle or pylint warnings, fix them and commit those fixes on the branch. If there are unit test errors (generated by pytest), fix them and commit those fixes on the branch. If there are clitest or runtest errors, fix them and commit those fixes on the branch. The phrase "fix them" means fix the code changes being proposed on your branch, not changing the test to make the errors go away.

6. After passing all the tests on your branch, check that the unit tests in the etitaxanalyzer/tests directory still provide complete code coverage. Generate a unit-test code-coverage report using this command:
   make coverage
   If coverage has fallen below 100%, add one or more new unit tests to regain complete (100%) code coverage.

7. After doing the above, ask for a review of your branch. If you branch is private, you can do this in one of two ways.

   • The first way is to make the branch public by using the following command:
     fossil publish the-branch-name
     where the-branch-name is the same name you used when creating the new branch.
   • The second way is to send the team member who will do the review a bundle containing your private branch. Create a bundle using the following command:
     fossil bundle export the-branch-name-bundle --branch the-branch-name
     and then attach the generated bundle file to an email message addressed to the reviewer.

8. After the review process has been completed, you can commit your public branch to trunk using the following commands:
   fossil checkout trunk     [to switch to trunk branch]
   fossil update trunk
fossil merge --integrate the-branch-name
fossil commit -m "Merge commit message here."