# 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`

[GNU Make]: https://www.gnu.org/software/make/
[uv]: https://docs.astral.sh/uv/
[Bash]: https://www.gnu.org/software/bash/


## 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`