Project

Building

Building the ndice project requires the following tools:

  • GNU Make 3.81 or later for build and task management

  • Astral’s uv for Python version and dependency management

  • A Bash compatible shell with common POSIX utilities, including cat, find, printf, rm and touch

Makefile Targets

By default, running make in the project root directory has the same effect as running make check: it will install dependencies, run unit tests with code coverage, check formatting and types, build documentation and build the package distribution. All output will be placed in the directory specified by the make variable TMP, which defaults to ./tmp/ in the project root.

Code coverage reports are written to $(TMP)/coverage-report, docs are written to $(TMP)/docs and the built package distribution is written to $(TMP)/dist.

The clean target removes the TMP directory; the clobber target runs clean and also removes the .venv directory.

Other useful targets include pub-pkg and pub-test-pkg for publishing the built package to PyPI and TestPyPI respectively, bump for incrementing the package version, and reformat for reformatting the source code.

Secrets

The pub-pkg and pub-test-pkg targets will look for API keys for pypi.org and test.pypi.org respectively in the secrets/ directory.

Releasing

These are the steps and considerations for preparing a release.

  1. Check that dependencies are up to date

  2. Check that the “Unreleased” section of CHANGELOG.md is up to date

  3. Run make bump optionally with NEW_VERSION=X.Y.Z, which does the following:

    1. make clean

    2. update the version in pyproject.toml

    3. update the version in src/ndice/__init__.py

    4. update the release in docs/conf.py

    5. add a new version section to CHANGELOG.md

    6. make check, which will update uv.lock

    7. git add . to add all changed files

    8. git commit --file tmp/commit_message.txt

    9. git tag -a $(<tmp/tag_name.txt) --file tmp/tag_message.txt

  4. Review and validate the new commit and tag

  5. Run git push and check that CI ran successfully

  6. git push origin $(<tmp/tag_name.txt)

  7. Build and publish the new package version

    1. make clean

    2. make check

    3. make pub-test-pkg

    4. make check-pub-test-pkg

    5. make pub-pkg

    6. make check-pub-pkg

    7. make pub-docs

    8. make check-pub-docs