Skip to content

Contributing to NZ Microsimulation Model

We welcome contributions to the NZ Microsimulation Model! By contributing, you help us create a more transparent, accessible, and extensible model for New Zealand's tax and transfer system.

Branching Strategy

To ensure a clean and maintainable codebase, we follow a simple branching strategy:

  1. main branch: This branch is considered stable and should always be in a deployable state. Direct pushes to main are not allowed.
  2. Feature branches: All new features and bug fixes should be developed in separate branches, created from the main branch.
    • Branch names should be descriptive, e.g., feature/add-new-benefit, fix/calculation-error.
  3. Pull Requests (PRs): Once a feature or fix is complete, open a pull request to merge the changes into the main branch.
    • PRs should include a clear description of the changes and reference any relevant issues.
    • All PRs must pass the automated checks (linting and testing) before they can be merged.

Development Workflow

For more detailed development guidelines, see our DEVELOPMENT.md file.

1. Fork and Clone the Repository

First, fork this repository to your own GitHub account. Then, clone your forked repository to your local machine:

git clone https://github.com/your-username/nztaxmicrosim.git
cd nztaxmicrosim

2. Set Up Your Development Environment

This project uses pyproject.toml for dependency management. We recommend using a virtual environment.

python -m venv .venv
source .venv/bin/activate  # On Windows, use `.venv\Scripts\activate`
pip install -e .

3. Install Pre-commit Hooks

We use pre-commit to ensure code quality and consistency. Install the hooks by running:

pre-commit install

These hooks will automatically run ruff checks and formatting on your staged files before each commit.

4. Create a New Branch

Create a new branch for your feature or bug fix from the main branch:

git checkout main
git pull origin main
git checkout -b feature/your-feature-name

5. Make Your Changes and Log Them

Implement your changes. Remember to follow the existing code style and conventions. Once you have made significant progress, add an entry to the docs/development_log.md file.

6. Run Tests

Ensure your changes haven't introduced any regressions by running the test suite. Before running tests, install the project dependencies using pip install -e . or make install-dev-deps if you haven't already: Before executing the tests, make sure all development dependencies are installed. You can install them with the provided Make target:

make install-dev-deps

After the dependencies are installed, run the test suite:

pytest

7. Lint and Format Your Code

Before committing, ensure your code adheres to the project's linting and formatting standards using Ruff:

ruff check .
ruff format .

To automatically fix most linting issues, run:

ruff check . --fix

8. Commit Your Changes

Commit your changes with a clear and concise commit message. The pre-commit hooks will run automatically at this stage.

git add .
git commit -m "feat: Add a new feature" # or "fix: Fix a bug"

9. Push to Your Fork

git push origin feature/your-feature-name

10. Create a Pull Request

Go to the original repository on GitHub and open a pull request from your forked branch to the main branch. Provide a clear description of your changes and reference any relevant issues.

Thank you for contributing!