Add developer notes to website and move to dynamic versioning by cpjordan · Pull Request #461 · thetisproject/thetis

cpjordan · 2026-06-13T18:05:04Z

This PR updates the Thetis release workflow and switches package versions to dynamic git-based versioning.

What Changed

Added developer notes for managing main and release.
Documented the hard-reset workflow for major Firedrake releases:
- tag the old release state;
- hard-reset release to a vetted main commit;
- tag the new release state.
Clarified that most fixes go to main first.
Clarified when release should be updated and tagged.
Updated install docs - they are release focussed, otherwise re-directed to developer notes.
Added a way to download only examples/demos without cloning all of Thetis.

Versioning
Propose that Thetis now uses dynamic versioning with setuptools-scm.

main: YYYY.M.devN
- Example: 2026.6.dev4
release: YYYY.M.postN
- Example: 2026.4.post0, 2026.4.post1

Why Packaging Changed
Previously, the version was hard-coded in pyproject.toml, so it had to be edited manually.
This PR makes git tags the source of truth instead. It removes old Versioneer files and uses setuptools-scm so package versions follow the current branch/tag state.
This also avoids confusion with Firedrake patch versions: Thetis 2026.4.post1 does not imply it matches Firedrake 2026.4.1. Firedrake might make lots of release patches and get to e.g. 2026.4.5, with no Thetis changes at all - it would confuse me that there was only a Thetis 2026.4.0 - hence adding post to differentiate.

stephankramer

Looking really good. Agree with almost all of it. Just some clarifications.

Main sticky point for me is that we need to think a bit more about how we ensure the release after a reset is actually tested before we publish it. The whole point about stable release tags is that we can go back to a known stable and tested version, that is known to work with a certain release version of Firedrake, or in the associated container. For the patch release .postN, N>1 this is guaranteed through github's CI but the workflow for the release reset doesn't. It should be that release at that point is the same as main, which should have been recently tested against firedrake main, which should be close to the just released firedrake release. However that's still a bit approximate, and in particular in the run-up to release firedrake main can change quite rapidly. What we want to guarantee is that the release version runs correctly in the latest firedrake release container. You could do this locally (in a docker container) but that's a bit messy and doesn't guarantee you've done exactly the same steps as we've set up in CI. We can't easily do this via a "draft" PR, because if the base is set to main, it will run the wrong container, and if the base is set to "release" it may have conflicts with the extra commits from current release. We could just do the force push to release, github will then trigger the push.yml workflow, and cross our fingers that it passes and then tag .post0 - but what to do if it doesn't pass?

stephankramer · 2026-06-15T11:09:10Z

   pip install -e .

-.. note::
+In an editable install, ``git pull`` updates the Thetis source code, but it does


Suggested change

In an editable install, ``git pull`` updates the Thetis source code, but it does

In an editable install, ``git pull`` updates the Thetis source code and these changes take immediate effect in your (run-time) python environment, but it does

Just to clarify that of course "git pull" always updates the source code, it's just that in an editable install these changes are also the ones that get imported.

stephankramer · 2026-06-15T13:14:10Z

+   svn export https://github.com/thetisproject/thetis/branches/release/examples thetis-examples/examples
+   svn export https://github.com/thetisproject/thetis/branches/release/demos thetis-examples/demos


This does not actually work! I presume you asked copilot - which gave me the same suggestion. So did claude. When I complained, it said "You're right, GitHub deprecated SVN support in 2023. Here are the working alternatives".
For people that want to access the demo and examples but want to avoid git, I would just point to https://api.github.com/repos/thetisproject/thetis/tarball/release which gives you a .tar.gz of release. If you want command line instructions use curl -JLO to get a properly named .tar.gz file, or use curl -L https://api.github.com/repos/thetisproject/thetis/tarball/release | tar xz to download and extract in one line.

stephankramer · 2026-06-15T13:24:50Z

+  render as expected (build the Sphinx site locally if you edited
+  ``docs/source/*``).


Suggested change

render as expected (build the Sphinx site locally if you edited

``docs/source/*``).

render as expected (build the Sphinx site locally, using ``make html`` in the ``docs/`` directory, if you edited

``docs/source/*``).

stephankramer · 2026-06-15T13:42:12Z

+* Between these reset points, avoid routine backports. Only patch ``release`` if
+  the current stable line has a release-only issue, or if an urgent shared bug
+  must be shipped before the next reset.


I feel this could be a bit clearer. I personally wouldn't want to discourage "less urgent" bug-fixes to be cherry-picked to release. What I would explicitly want to proscribe: new functionality, rewrites of a substantial part of a routine - anything with the potential to introduce new bugs - and in particular any API changes: a script that runs against some release version, should still run against any further patch levels.

stephankramer · 2026-06-15T13:47:25Z

+   possible (squash merge, or rebase merge if enabled). If using squash merge,
+   keep the original ``cherry picked from`` line or mention the source ``main``
+   PR/commit in the squash commit message.
+4. If this produces a new published release state, tag the resulting


When would it not "produce a new published release state" ?

stephankramer · 2026-06-15T15:05:01Z

+is built with Sphinx (see ``docs/Makefile`` and ``docs/source/conf.py``).
+
+Thetis has a single published documentation website. The published site is
+updated whenever the ``release`` branch is updated, and it must be built from


Suggested change

updated whenever the ``release`` branch is updated, and it must be built from

updated whenever the documentation content in the ``release`` branch is updated, and it must be built from

stephankramer · 2026-06-15T15:18:24Z

+   If the change is intended for the published website, the PR must target
+   ``release`` (since the published website is built from ``release``). It is
+   fine to iterate on documentation changes in a PR targeting ``main``, but do
+   not publish a website build from ``main``.


This now goes against our policy to in-principle merge into main first. If a website update goes into release only, it will disappear on the next reset.

stephankramer · 2026-06-15T15:34:10Z

+   ``docs/build/html/`` into the ``thetisproject.github.io`` repository and
+   merge there as well.


Clarify: although it adds another round of waiting for approval, I think it can be worth doing this via a PR as well - I wouldn't read the whole thing again (some of it is auto-generated) but it's quick to check people have done the correct thing (also for yourself). It's easy to introduce some unintended changes. So maybe: "It is encouraged to do this via a PR and to check on github that all changes are as intended. If unsure, ask for a review" - I think it's currently unprotected. Would also be happy with a stricter approach if we add standard branch protection.

stephankramer · 2026-06-15T15:35:56Z

+Patel, M.D., Smyth, A.S.M., Angeloudis, A. and Adcock T.A.A.:
+The interplay and incremental development of tidal stream arrays in the Pentland Firth.
+*J. Ocean Eng. Mar. Energy*, 9,
+doi: `10.1007/s40722-026-00490-5 <https://doi.org/10.1007/s40722-026-00490-5>`_, 2026.
+
+Guichard J., Rawlinson-Smith R., Coles D. and Greaves D.:
+Energy storage from a wind, tidal, and wave farm via hydrogen.
+*Front. Energy Res.* 14, p. 1732813,
+doi: `10.3389/fenrg.2026.1732813 <https://doi.org/10.3389/fenrg.2026.1732813>`_, 2026.
+
+Bolhuis, S., Alday, M. and Lavidas, G.:
+Tidal stream energy in the Netherlands—Resource assessment and future effects due to mean sea level rise,
+*Renewable Energy*, 256, Part F, p. 124214,
+doi: `10.1016/j.renene.2025.124214 <https://doi.org/10.1016/j.renene.2025.124214>`_, 2026.
+


This is another case, where it'd be happy for a publications update to be cherry-picked into release so that the website is updated immediately...

stephankramer · 2026-06-15T15:48:42Z

+from os.path import isfile

-setup(scripts=glob('scripts/*'))
+setup(scripts=[path for path in glob('scripts/*') if isfile(path)])


Why would we have directories under scripts/ ? And if so, would they contain scripts that need discovering?

stephankramer · 2026-06-15T17:34:48Z

How about we introduce another special branch name "release-candidate" that whenever you push to it triggers a CI run in the firedrake: latest container (i.e. add it to the rules in push.yml). So you:

hard-reset release-candidate to main
force push release-candidate
check the actions tab to see that it passes
if it doesn't implement necessary fixes directly on release-candidate, and push them until it works - you can rewrite the fix commits as much as you like as long as it keeps current main as its base unchanged.
So at this point release-candidate should pass CI, then:
If new commits were introduced in 4. fast-forward main to release-candidate, push to main even it breaks CI (by passing branch protection that requires a PR but only using git push without --force to ensure we're not rewriting history)
reset release to release-candidate/main
force push release
tag release
if you have broken main under 5. open up a PR as normal to fix it

To clarify point 5+9: if we're a little late (people are busy!) generating the new release after firedrake's, firedrake main may have moved on already. This may for instance mean that at the point that we try to generate a release, Thetis main is already broken against current firedrake main (even though it passed the last time the CI ran). At that point there's another rule we should introduce - as it went wrong the last time: as soon as new Firedrake release has been released, we should not accept any changes to main before we have finished the corresponding Thetis release. Otherwise we run the risk of only working with Firedrake main and (no longer) against the latest release, and these commits would have to be undone on the release branch. In any case, if fixes were needed under 4. chances are that firedrake main was already broken, so by-passing CI checks on main in step 5 is not a big deal.

A slightly simpler version of this would be to immediately push to release (as it currently is described) and immediately try to fix it directly on release if it doesn't pass CI (and then do 5. to 9.). Downside is that there's a window of time with an unstable release....

jhill1 · 2026-06-15T17:39:27Z

I like this process. It means if there are major issues with a release candidate we have time to implement any fixes without pressure.

cpjordan · 2026-06-16T18:33:15Z

Looking unlikely that I have time to fix this before I go away - back 29th June but happy for anyone else to move this forward in the meantime.

cpjordan added 4 commits June 13, 2026 18:53

Update project metadata and website basics

a4ffe06

Update website publications

e7ebcef

Use dynamic Thetis versioning

b588241

Document Thetis release workflow

a932c04

stephankramer requested changes Jun 15, 2026

View reviewed changes

	In an editable install, ``git pull`` updates the Thetis source code, but it does
	In an editable install, ``git pull`` updates the Thetis source code and these changes take immediate effect in your (run-time) python environment, but it does

		svn export https://github.com/thetisproject/thetis/branches/release/examples thetis-examples/examples
		svn export https://github.com/thetisproject/thetis/branches/release/demos thetis-examples/demos

		render as expected (build the Sphinx site locally if you edited
		``docs/source/*``).

	updated whenever the ``release`` branch is updated, and it must be built from
	updated whenever the documentation content in the ``release`` branch is updated, and it must be built from

		``docs/build/html/`` into the ``thetisproject.github.io`` repository and
		merge there as well.

Conversation

cpjordan commented Jun 13, 2026

Uh oh!

stephankramer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stephankramer commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jhill1 commented Jun 15, 2026

Uh oh!

cpjordan commented Jun 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

stephankramer commented Jun 15, 2026 •

edited

Loading