Using Makefile (Recommended)

The easiest way to set up your development environment is using the provided Makefile. This will handle all the setup steps automatically:

make setup

This will: - Install the package with development dependencies - Install pre-commit and pre-push hooks - Install all required Python versions via pyenv

After running make setup, remember to set your AIT_CONFIG:

export AIT_CONFIG=/path/to/ait-core/config/config.yaml

You can see all available Makefile targets by running:

make help

Alternatively: Manual Installation

Install the package in “editable” mode with all the development dependencies by running the following:

poetry install

As with a normal installation you will need to point AIT_CONFIG at the primary configuration file. You should consider saving this in your shell RC file or your virtual environment configuration files so you don’t have to reset with every new shell:

export AIT_CONFIG=/path/to/ait-core/config/config.yaml

You should configure pre-commit by running the following. This will install our pre-commit and pre-push hooks:

pre-commit install && pre-commit install -t pre-push

Finally, you should install the different Python versions that the project supports so they’re accessible to tox. Using pyenv is the easiest way to accomplish this:

cat .python-version | xargs -I{} pyenv install --skip-existing {}

Tox

Use tox to run a thorough build of the toolkit that checks test execution across different Python versions, verifies the docs build, runs the linting pipeline, and checks that the repo packages cleanly. Make sure you run tox in Poetry’s shell without another virtual environment active to avoid problems with tox finding different python versions for the tests. You can run all of the development tools with:

# Manual command:
tox

# Makefile equivalent:
make tox

You can see the available tox test environments by passing -l and execute a specific one by passing its name to -e. Run tox -h for more info.

Tests

Use pytest to manually run the test suite:

# Manual command:
pytest

# Makefile equivalent:
make test

Or via tox for a specific python version:

# Manual command:
tox -e py310

# Makefile equivalent:
make run-tests PY=py310

Code Checks

We run black, flake8, mypy, and a few other minor checkers on the code base. Our linting and code check pipeline is run whenever you commit or push. If you’d like to run it manually you can do so with the following:

pre_commit run --color=always {posargs:--all}

Individual calls to the tools are configured in .pre-commit-config.yaml. If you’d like to run a specific tool on its own you can see how we call them there.

You can run all the linting tools with tox as well:

# Manual command:
tox -e lint

# Makefile equivalent:
make lint

Documentation

AIT uses Sphinx to build its documentation. You can build the documentation with:

# Manual command:
poetry run build_sphinx

# Makefile equivalent:
make docs

To view the documentation, open doc/build/html/index.html in a web browser. If you just want to check that the docs build is working you can use tox:

tox -e docs

If you need to update the auto-generated documentation you can run the following command to rebuild all of the package documentation:

sphinx-apidoc --separate --force --no-toc -o doc/source ait --implicit-namespaces

Please make sure to update the docs if changes in a ticket result in the documentation being out of date.

Issue Tracking

All changes need to be made against one or more tickets for tracking purposes. AIT uses GitHub Issues along with Zenhub to track issue in the project. All tickets should have (outside of rare edge-cases):

• A concise title

• An in-depth description of the problem / request. If reporting a bug, the description should include information on how to reproduce the bug. Also include the version of the code where you’re seeing the bug.

If you’re going to begin work on a ticket make sure to progress the ticket through the various Pipeline steps as appropriate as well as assigning yourself as an Assignee. If you lack sufficient permissions to do so you can post on the ticket asking for the above to be done for you.

Commit Messages

AIT projects take a fairly standard approach to commit message formatting. You can checkout Tim Pope’s blog for a good starting point to figuring out how to format your commit messages. All commit messages should reference a ticket in their title / summary line:

Issue #248 - Show an example commit message title

This makes sure that tickets are updated on GitHub with references to commits that are related to them.

Commit should always be atomic. Keep solutions isolated whenever possible. Filler commits such as “clean up white space” or “fix typo” should be rebased out before making a pull request. Please ensure your commit history is clean and meaningful!

Code Formatting and Style

AIT makes a best-effort attempt at sticking with PEP-8 conventions. This is enforced automatically by black and checked by flake8. You should run the pre-commit linting pipeline on any changes you make.

Testing

We do our best to make sure that all of our changes are tested. If you’re fixing a bug you should always have an accompanying unit test to ensure we don’t regress!

Check the Developer Tips section below for information on running each repository’s test suite.

Pull Requests and Feature Branches

All changes should be isolated to a feature branch that links to a ticket. The standard across AIT projects is to use issue-### for branch names where ### is the issue number found on GitHub.

The title of a pull request should include a reference to the ticket being fixed as mentioned for commit messages. The description of a pull request should provide an in-depth explanation of the changes present. Note, if you wrote good commit messages this step should be easy!

Any tickets that are resolved by the pull request should be referenced with GitHub’s syntax for closing out tickets. Assuming the above ticket we would have the following in a pull request description:

Changes are required to be reviewed by at least one member of the AIT PMC/Committers groups, tests must pass, and the branch must be up to date with master before changes will be merged. If changes are made as part of code review please ensure your commit history is cleaned up.