Release v1.5.0

[tbody-cfs]

Propose to make a v1.5.0 release since it's been 8 months since the last release.

Add CHANGELOG.md with release notes since v1.4.1 and bump docs version to 1.5.0. Also fix pre-existing ruff errors in docs/sphinx/conf.py (unused sys import, E402 on deliberate late import).

Changes since v1.4.1 (→ v1.5.0)

~122 PRs merged since the v1.4.1 tag (2025-12-09). Grouped:

Physics & model features

• 1D fieldline geometry (Geometry 1D modifications #232) — reformulated cross-field transport, new geometry terms & diagnostics
• Sheath boundary features (Sheath boundary features #574) incl. supersonic handling; sin_alpha as Field3D
• External Apar flutter (External Apar flutter #554) — electromagnetic
• Target pump (Add target pump #491)
• Viscous heating & energy conservation (Viscous heating and energy conservation #455)
• neutral_full_velocity transport coefficient (neutral_full_velocity: adding transport coef  #454); optional nonorthogonal operators in neutral_mixed (Make neutral_mixed nonorthogonal operators optional  #497)
• Numerical method choices (Numerical method choices #578); relax-potential component (Relax potential component #465)

Reactions / component framework refactor

• Component metadata system (Add metadata to component objects #596); state-variable access control in transform() (Control access to state variables in transform method #421)
• Decouple reaction data (Decouple reaction data #534); reaction classes into hermes namespace (Add reaction classes to hermes namespace #538)
• Closure refactor to allow other forms (Refactor closure so can use other forms #399); H-isotope charge-exchange moved to new reactions framework (Refactor H isotope charge exchange to use the new reactions framework. #398)

Bug fixes

• Guard-cell communication fixes in vorticity & braginskii_ion_viscosity (Fix communications in vorticity and braginskii_ion_viscosity #589)
• Fast-recycling heat flux (Fix fast recycling heat flux #494); relax_potential radial BC (relax_potential: Fix a bug with radial BC. #528); sheath_boundary_simple (Fix sheath boundary simple 2 #482)
• Numerous permission/AA fixes (braginskii_conduction: Apar_flutter read permission #540, classical_diffusion: add AA permissions #517, sheath_closure: fix permissions typo #509, Suppress permission warnings #468, Fix AA permissions in neutral_boundary #466)

BOUT++ / build

• Adopt BOUT++ template (lazy) expressions (Updating to BOUT++ with template expressions #585); several BOUT++ version bumps (Upgrade BOUT++ to latest next #440, Update to BOUT++ 7d28d67 (next branch) #489, Update BOUT++ version #563); spack builds BOUT++ as separate package (Update the spack config to build BOUT++ as a separate package #376, Updates to allow builds with spack v1. #479); min CMake 3.25 (Set min CMake version to 3.25 #514)
• spack builds of hermes-3 / BOUT-dev default to RelWithDebInfo, and BOUT-Spack updated to fix python dependency versions for tests (Update BOUT-Spack: fixes python dependency versions for tests. #619)

Testing

• More unit tests (More unit tests #483), energy tests (Viscous heating and energy conservation #455), 2D integrated CI test (Add 2D integrated test to CI #473), D-T-He 1D-recycling regression test (D-T-He 1D-recycling integrated (regression) test. #425), nonorthogonal MMS test (Nonorthogonal with minimal differential operators MMS test. #285), faster/cleaned-up tests (Shorten timestep on 2D-production/recycling tests #533, Cleanup tests: Do not download if present #610–Cleanup tests: use mpirun as expected. #612)

Docs & CI/infra

• Docs: diamagnetic_drift (Fix typos, links, and improve diamagnetic_drift description. #558), installation (Correct some syntax errors and typos in the installation docs #569, Update spack installation instructions #505), sphinx/neutral_mixed fixes (Fix some sphinx warnings #516, Fix neutral_mixed equations in docs #458)
• CI/docker: multi-arch images (Update docker builds to work for multi-arch, with smart reuse of built packages #601), auto-delete old images (Add action to delete old or untagged images #606), stale-bot (Add workflow to close stale PRs and issues #607, Stale go live #617), tidy actions (Tidy up actions #616), clang-format/python-format CI (CI: Add clang-format for changes #485, CI: Add python-format #486, Copy auto-formatting.yml action from BOUT++ #510, Copy CI formatting from BOUT++ #545), auto Python-dep updates (Automatic PRs to update xhermes/boutdata/xbout #582, Update Python test dependency SHAs #618), PR template (Add Github PR template #595)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 57.51%. Comparing base (293d166) to head (9f075c5).
⚠️ Report is 3 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #620   +/-   ##
=======================================
  Coverage   57.51%   57.51%           
=======================================
  Files          98       98           
  Lines       10239    10239           
  Branches     1469     1469           
=======================================
  Hits         5889     5889           
  Misses       3758     3758           
  Partials      592      592           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[mikekryjak]

With this many PRs maybe we should skip some versions? @cmacmackin what does best practice say?
I think it could be a good time for a release, because we are due some major changes/improvements - my fluid neutral work and the component sort algorithm. A release now would add a tag before these changes, which would justify additional new releases when merged.

[cmacmackin]

First off, I'd recommend adding #619 to this, as it was just merged.

With this many PRs maybe we should skip some versions? @cmacmackin what does best practice say?

Generally you don't "skip releases". However, in the most common versioning scheme, this would be more than just a "patch" level release. Most software uses what is called "semantic versioning". In this scheme versions contain three numbers, expressed as X.Y.Z. Each number has the following meaning:

• X: The "major version". This is incremented when changes are made that are not backwards compatible. You try to avoid this.
• Y: The "minor version". This is incremented when new features are added.
• Z: The "patch version". This is for bugfixes.

If you follow semantic versioning then this release is at least a minor version (i.e., v1.5.0). However, if there are changes that mean existing user's configurations will no longer work then it would be a major release (i.e., v2.0.0).

From what I can tell, BOUT++ and Hemres-3 have not tended to follow semantic versioning, or at least not rigorously. I'm not entirely clear on what the criteria are for incrementing each version number. However, I would be inclined to say that a release with new features like this should at least be given v1.5.0.

[tbody-cfs]

Have rebased onto latest master and bumped the version tag to v1.5.0

[mikekryjak]

Ideally, I would quite like for boutproject/BOUT-dev#3426 to be in master for the release, because right now most CVODE users will get a confusing error message due to a change in the preconditioning selection options. Unfortunately the latest BOUT++ next also includes boutproject/BOUT-dev#3419 which currently won't compile. Work is needed on the Hermes-3 side to delete operators on our side and point them at their versions newly moved to BOUT++.

[tbody-cfs]

Sounds good @mikekryjak. Once BOUT is updated, ping me here and I'll update this PR. Alternately, feel free to pick up this PR yourself.