Release Procedures#

These notes are meant for a maintainer to create official releases of MOLE.

In preparing a release, create a branch to hold pre-release commits. We ideally want all release mechanics to be in one commit, which will then be tagged.

Core Library Release#

Some minor bookkeeping updates are needed when releasing a new version of MOLE.

The version number must be updated in the following files:

mole/CITATION.cff: update the authors, doi, and date-released fields if needed
mole/README.md: in the How to Cite section
mole/doc/sphinx/source/conf.py: the release field

Additionally, the change log should be generated and reviewed.

Use git log --first-parent v1.0.. to get a sense of the pull requests that have been merged since the last release and thus might warrant emphasizing in the change log.

While doing this, gather a couple sentences for key features to highlight on GitHub releases.

Quality control and good citizenry#

Testing: Ensure all tests pass on supported platforms:
- Run make run_tests for C++ tests
- Run make run_matlab_octave_tests for MATLAB/Octave tests
- Verify CI passes on all platforms (Ubuntu, macOS)
Documentation: Ensure documentation builds successfully:
- Check that the documentation workflow passes
- Verify examples work correctly
- Review any new documentation for accuracy
Dependencies: Check that all dependencies are properly specified and up-to-date:
- Verify CMake builds work on supported platforms
- Check that installation instructions are current

Tagging and releasing on GitHub#

Prepare the release commit:
```
git commit -am "MOLE v1.1.0"
```
More frequently, this is amending the commit message on an in-progress commit, after rebasing if applicable on latest main.
Push and review:
```
git push
```
This updates the PR holding release; opportunity for others to review.

Merge to main:

git switch main && git merge --ff-only HEAD@{1}

Fast-forward merge into main.

Tag the release:
```
git tag -a v1.1.0 -m "MOLE v1.1.0"
```
Push tag:
```
git push origin main v1.1.0
```
Create GitHub Release:
- Go to GitHub releases page
- Click “Draft a new release”
- Select the newly created tag
- Use the tag name as the release title
- Copy release notes from the automated generation (see below)
- Add a few sentences highlighting key features
- Publish the release

Archive Documentation on Zenodo#

For DOI-bearing releases:

Generate documentation PDF: The documentation workflow automatically generates a PDF version
Update Zenodo record:
- Visit the MOLE Zenodo record (update URL as needed)
- Click “New version”
- Upload the generated PDF documentation
- Update author information if applicable
- Publish the new version
Update repository with new DOI:
- Update CITATION.cff with the new DOI
- Update README.md with the new DOI if referenced
- Create a follow-up PR with these updates

Automated Release Notes#

MOLE uses GitHub Actions to automatically generate release notes when a new tag is pushed.

How it works#

The release notes generation workflow:

Triggers automatically when a tag matching v* is pushed
Analyzes commits since the last release
Generates release notes based on commit messages and PR titles
Creates or updates the GitHub release with the generated notes

Manual review and adjustment#

While automation helps, always review the generated release notes:

Check for accuracy and completeness
Add context for major changes
Highlight breaking changes or important updates
Ensure proper formatting and readability

If manual adjustments are needed, you can use:

git log --first-parent v1.0..

to review changes since the last release.

Version Numbering#

MOLE follows semantic versioning:

MAJOR version (X.y.z): Incompatible API changes
MINOR version (x.Y.z): New functionality in a backwards compatible manner
PATCH version (x.y.Z): Backwards compatible bug fixes

Examples:

v1.0.0 → v1.1.0: New features added (documentation system, test suites)
v1.1.0 → v1.1.1: Bug fixes only
v1.1.0 → v2.0.0: Breaking changes to API

Troubleshooting#

Common Issues#

Tag already exists: If you need to retag, delete the tag locally and remotely:
```
git tag -d v1.1.0
git push origin :refs/tags/v1.1.0
```
CI failures: Ensure all workflows pass before tagging. Check:
- Build and test workflows
- Documentation generation
- Linting and code quality
Documentation issues: If documentation fails to build:
- Check for missing dependencies
- Verify all referenced files exist
- Review recent changes to documentation source

Getting Help#

If you encounter issues during the release process:

Check existing GitHub issues for similar problems
Review the CI/CD workflow logs for detailed error messages
Consult the project maintainers
Refer to the contributing guidelines

Post-Release Tasks#

After a successful release:

Update development version: Consider updating version numbers to indicate development status
Monitor for issues: Watch for bug reports related to the new release
Update documentation: Ensure all documentation reflects the latest release
Community engagement: Announce the release through appropriate channels

MOLE.jl Release#

The version of the MOLE.jl package needs to be updated in the Project.toml file, located in mole/julia/MOLE.jl.

This should be done in a separate, atomic PR.

Once the PR is merged into the main branch, comment under the specific commit in main (not in the PR conversation) and invoke the @juliaRegistrator bot, like in this commit. The key words and markdown formatted text to be added in the comment are the following:

@JuliaRegistrator register branch=main subdir=julia/MOLE.jl

Release notes:

## Breaking changes

- Describe changes here

Release Procedures

Contents