Release Procedure

Use this checklist for releases from master. Versions are taken from Git tags through setuptools_scm. Tags must use the form vX.Y.Z.

1. Confirm the release candidate

Check that the intended release commit is clean and tested:

git status --short
git log --oneline --decorate -5
ruff check orgui
pytest orgui/datautils/xrayutils/test/test_HKLcalc.py
pytest orgui/datautils/xrayutils/test/test_DetectorCalibration.py
pytest orgui/datautils/xrayutils/test/test_CTRcalc.py
python -m build
python -m twine check dist/*

Manual GUI/science smoke test:

  • install from a clean environment or from the built wheel

  • start the GUI and confirm clean startup

  • load at least one examples/ configuration

  • check source/detector units: energy in keV, wavelength in Angstrom, SDD in m, pixel size in m, and detector center in pixels

  • load a representative image or scan

  • run one known UB/orientation calculation

  • run one representative integration workflow

  • compare CTR or structure-factor output with a previous release or reference when scientific code changed

  • start CLI/headless mode when shared loading or logging code changed

2. Update CHANGELOG.md and write release notes

2.1 Automatic CHANGELOG using cliff

Choose the bump type manually: patch for bug fixes, documentation, packaging, and compatibility fixes; minor for backwards-compatible features. Replace patch with minor when appropriate. A major version change implies substantial API or other user-facing breaking changes and requires a dedicated release workflow.

Preview the next version:

git cliff --bumped-version --bump patch

Prepend only unreleased changes to CHANGELOG.md:

git cliff --unreleased --bump patch --prepend CHANGELOG.md

Then inspect the changelog. This command prepends the new release section, but manual cleanup is still required:

  • remove the duplicated # Changelog title and introductory text if they appear below the new release section

  • add the new compare link near the bottom of CHANGELOG.md before the existing release links, for example:

    [1.4.2]: https://github.com/tifuchs/orGUI/compare/v1.4.1..v1.4.2

2.2 Add release notes

Edit the new release section by hand. Place the user-facing release notes directly below the new ## [X.Y.Z] heading and commit range, and above the generated commit groups such as ### Added or ### Fixed.

Include only high-signal notes:

  • one short sentence classifying the release, such as bugfix, maintenance, or feature release

  • important user-visible changes

  • upgrade or dependency warnings

  • known issues

  • scientific correctness fixes that affect calculations or previous results

Example:

## [1.4.1] (2026-03-27)

[260ab5d](https://github.com/tifuchs/orGUI/commit/260ab5d)...[3f5ce1a](https://github.com/tifuchs/orGUI/commit/3f5ce1a)

This is a bugfix and maintenance release.

**Attention: pyFAI versions 2025.12.0, 2025.12.1 and 2026.2.0 cause a
software crash when selecting a detector in the machine parameters.**

Two critical bugs were fixed that affect physics calculations:

- Allowed Bragg reflections close to the search bounds were sometimes not
  found.
- The complex phase of the Fourier components rho_G of the electron density
  along z was incorrectly calculated.

### Added

- Generated commit list starts here.

Regenerate the documentation release-notes page:

python doc\generate_release_notes.py

Test the Sphinx documentation build:

python -m sphinx -b html doc\source doc\build\html

3. Commit, tag, and push the release

git diff -- CHANGELOG.md doc\source\release_notes.rst
git add CHANGELOG.md doc\source\release_notes.rst
git commit -m "docs: update changelog for vX.Y.Z"
git tag -a vX.Y.Z -m "Release vX.Y.Z"
git show --stat vX.Y.Z
git push origin master
git push origin vX.Y.Z

Use the version from the new CHANGELOG.md release section for vX.Y.Z. The tag push starts .github/workflows/release.yml.

4. Verify the workflow

Check that GitHub Actions:

  • builds the wheel and source distribution

  • runs twine check

  • extracts the release notes from CHANGELOG.md

  • creates the GitHub release

  • publishes to PyPI

If publishing to PyPI has already succeeded, do not reuse the same version number for a fix.

5. Verify the published package

python -m venv .venv-release-check
.\.venv-release-check\Scripts\python -m pip install --upgrade pip
.\.venv-release-check\Scripts\python -m pip install "orGUI[full]==X.Y.Z"
.\.venv-release-check\Scripts\python -c "import orgui; print(orgui.__version__)"

Confirm the GitHub release, PyPI page, attached artifacts, and Read the Docs build.