Skip to content

Latest commit

 

History

History
118 lines (74 loc) · 4.5 KB

DEVELOPMENT.md

File metadata and controls

118 lines (74 loc) · 4.5 KB

Development

This project uses the Hatch project manager (installation instructions).

Hatch automatically manages dependencies and runs testing, type checking, and other operations in isolated environments.

Testing

You can run the tests on your local machine with:

hatch test

The test command supports options such as -c for measuring test coverage, -a for testing with a matrix of Python versions, and appending an argument like tests/test_validator.py::test_validate_expert_answer for running a single test.

Type checking

You can run the mypy static type checker with:

hatch run types:check

Formatting and linting

You can run the Ruff formatter and linter with:

hatch fmt

This will automatically make safe fixes to your code. If you want to only check your files without making modifications, run hatch fmt --check.

Pre-commit

You can install the pre-commit hooks to automatically run type checking, formatting, and linting on every commit.

First, install pre-commit, for example, with pipx:

pipx install pre-commit

Then, install the hooks:

pre-commit install

Documentation

You can preview the MkDocs site locally at http://localhost:8000/ with:

hatch run docs:serve

This will live-reload the site as you make changes. You can run hatch run docs:build to build the compiled site into the site/ directory.

Packaging

You can use hatch build to create build artifacts, a source distribution ("sdist") and a built distribution ("wheel").

You can use hatch publish if you want to manually publish build artifacts to PyPI.

Automated releases

Automated releases are handled by the release workflow which is triggered by pushing a new tag to the repository. To create a new release:

  1. Bump the version in tlm/__about__.py. You can use the hatch version command to do this.
  2. Ensure that the release notes are updated in CHANGELOG.md:
    • You should update the [Unreleased] header to the new version and add a new [Unreleased] section at the top of the file.
    • You should update the link for the [Unreleased] code and add a new link to the code diff for the new version.
  3. Create a PR and merge these changes into the main branch.
  4. After the PR is merged into main, create a new release tag by running git tag v<output of hatch version> (i.e. git tag v0.0.1).
  5. Push the tag to the repository by running git push origin <tag>.
  6. This will trigger the release workflow which will build the package, create a release on GitHub, and publish the package version to PyPI. The GitHub release notes will be automatically generated from the changelog.

How to build and install the package locally

You may want to build and install the package locally - for example, to see how your changes affect other Python code in a script or Jupyter notebook.

To do this, you can build the package with hatch build and then install it in your local environment with pip install dist/tlm-<version>-py3-none-any.whl.

Alternatively, you can use pip install -e /path/to/tlm to install the package from your local code. Note that if you make further local changes after that, you may need to reload the module, i.e. reload(tlm), or restart the kernel.

Continuous integration

Tests, type checking, and formatting/linting are checked in the CI workflow.