Contributing

Test protection process

OLM treats tests as protected review assets. In a workflow where code and tests may both be edited by bots or AI tools, passing tests is not enough: reviewers also need one place to see when tests were added, removed, renamed, or changed.

The test manifest is that review surface:

  • testing/test_functions_manifest.txt lists every discovered test function and a short hash of that test function body.

  • testing/scale_olm_test.py verifies that the manifest still matches the test suite during pytest.

  • scripts/regenerate_manifest.py refreshes the manifest after an intentional test-suite change.

When a pull request intentionally changes tests, run:

python scripts/regenerate_manifest.py

Review the manifest diff before committing it. A new test should add one new hash:test_name entry. A changed test should update the hash for that test. A deleted or renamed test should remove or rename the corresponding entry. Treat unexpected manifest changes as a signal to inspect the test diff carefully.

The repository also uses CODEOWNERS to require owner review for the manifest, the manifest verifier, the regeneration script, the test workflow, the coverage policy, the auto-merge workflow, and the CODEOWNERS file itself. These files are the control plane for test and merge integrity.

codecov.yml defines the coverage policy. Project coverage uses the pull request base as the target with a 0% threshold, so total coverage must not go down. Pull requests that lower project coverage need additional tests or less untested code before their Codecov project status should pass.

ORIGEN Library Manager (OLM)

Documentation Status codecov

The latest stable version is v0.14.3.

OLM is a command-line utility that streamlines aspects of using the SCALE/ORIGEN library to solve nuclide inventory generation problems.

To install, use pip.

pip install scale-olm

Locations

The main development repository is hosted on GitHub with a read-only mirror on the ORNL-hosted GitLab.

Developing

The script dev.sh is provided to initialize the development environment.

$ git clone https://github.com/wawiesel/olm
$ cd olm
$ source dev.sh

This is all you should need to do. The following sections explain in more detail what happens when you run dev.sh.

Developer details

This section contains additional details on developing OLM.

Enable virtual environment

$ virtualenv venv
$ . venv/bin/activate
$ which python

If you get an error about missing virtualenv, you may need to install it.

$ pip install virtualenv

Install development dependencies

After enabling the virtual environment, install OLM with the optional dependencies needed for testing and documentation.

$ pip install --editable ".[test,docs,notebooks]"

The project metadata in pyproject.toml is the source of truth for package dependencies. The checked-in requirements.txt file is a pinned development snapshot. If you need to regenerate it after changing dependencies:

$ pip freeze | grep -v '^\-e'>requirements.txt

Enable a local install for testing

This command will enable any changes you make to instantly propagate to the executable you can run just with olm.

$ pip install --editable ".[test,docs,notebooks]"
$ olm
$ which olm

Creating docs

With the development environment installed, the docs may be created within the docs directory. With the following commands.

$ cd docs
$ make html
$ open build/html/index.html

Alternatively the PDF docs may be generated using the make latexpdf command. Note that the HTML docs are intended as the main documentation.

The following greatly simplifies iterating on documentation. Run this command and open your browser to http://localhost:8000.

sphinx-autobuild docs/source/ docs/build/html/

Notebooks

There are notebooks contained in notebooks which may be helpful for debugging or understanding how something is working. You may need to install your virtual environment kernel for the notebooks to work. You should use the local venv kernel instead of your default Python kernel so you have all the local packages at the correct versions.

$ ipython kernel install --name "venv" --user

Now, you can select the created kernel “venv” when you start Jupyter notebook or lab.

Notes about development

Click for CLI

We use the Click python library for command line. Here’s a nice video about click.

Commit messages

Follow these guidelines for commit messages.

Version updates

OLM uses semantic versioning. You should commit the relevant code with the usual description commit message.

Then run

  • bumpversion patch if you are fixing a bug

  • bumpversion minor if you are adding a new feature

  • bumpversion major if you are breaking backwards compatibility

When you push you need to git push --tags or configure your repo to always push tags:

#.git/config
[remote "origin"]
    push = +refs/heads/*:refs/heads/*
    push = +refs/tags/*:refs/tags/*

Pytest for unit tests

Locally for unit tests we use the pytest framework under the testing directory. All tests can be run simply like this from the root directory. Note we are using the pytest-xdist extension which allows parallel testing.

$ pytest -n 6 .

To run tests with coverage reporting:

$ pytest --cov=scale --cov-report=term-missing -n 6 .

To generate an HTML coverage report:

$ pytest --cov=scale --cov-report=html --cov-report=term-missing -n 6 .
$ open htmlcov/index.html

Black for commit formatting

The first time you do work on a clone, do this.

$ pre-commit install

This will use the Black formatter.

Docstrings and Doctest

Our goal is to have each function, module, and class with standard docstrings and a few doctests. You can run verbose tests on a specific module as follows.

$ pytest -v scale/olm/core.py