Contributing

Dependency management

Python dependencies

The requirements are listed in /pyproject.toml. We use uv to manage the project environment, including the uv.lock lockfile.

Create and activate the virtual environment with:

$ uv sync --dev
$ source .venb/bin/activate

Update the lockfile allowing package upgrades:

$ uv lock --upgrade

At this point you can also look up new versions beyond our constraints, e.g.:

$ uv run --with=pip pip list --outdated

The project lockfile documentation page describes other operations such as upgrading locked package versions individually.

pre-commit

pre-commit is a framework we use for managing and maintaining pre-commit hooks. The easiest way to discover and apply new updates is to run:

$ pre-commit autoupdate

Commit the changes and run pre-commit again with:

$ pre-commit run --all-files

Python version

There is a pinned version of Python in /.python-version that we use when packaging our Docker image and other development-oriented tools. The preference is to use the latest version available. Currently:

3.12.6

Releases

We aim to further enhance and automate our release process.

Please adhere to the following instructions:

1. Update the changelog (use scriv collect to populate CHANGELOG.rst). Submit these changes through a pull request and merge it once all checks have passed.

2. Confirm that the checks are also passing in main.

3. Create and push the git tag, e.g.:

   $ git tag v0.7.7
   $ git push origin refs/tags/v0.7.7
   

   This should have triggered the publishing workflow. Please confirm that the new version of the package is available on PyPI and that the container image has been published to the GitHub Container Registry.

Import FPR dataset from Archivematica

a3m loads the FPR dataset from a JSON document (a3m/fpr/migrations/initial-data.json) generated from the upstream Archivematica project. This section describes how to generate it:

In Archivematica, generate a dump with:

manage.py dumpdata --format=json fpr

Remove unused models from the document:

jq --sort-keys --indent 4 '[.[] | select(.model == "fpr.format" or .model == "fpr.formatgroup" or .model == "fpr.formatversion" or .model == "fpr.fpcommand" or .model == "fpr.fprule" or .model == "fpr.fptool")]' fpr-dumpdata.json > output.json

Replace the dataset:

mv output.json ../../a3m/fpr/migrations/initial-data.json

From the root directory, run the registry sanity checks:

pytest tests/test_registry.py

Based on the validation issues reported, fix as needed. Make sure that the fiwalk command is not using a ficonfig file.