Make a release - firedrakeproject/firedrake GitHub Wiki

Note that the processes here apply to the majority of Firedrake packages, not just Firedrake itself. Some packages (e.g. petsctools) do not have a release branch and so there is no difference between a major and patch release.

How to make a patch release

  1. Create a branch off of release with a suitable name (e.g. myusername/2025.4.3rc).
  2. Address all # TODO RELEASE comments found in the code. These will mostly be to use specific version of downstream packages instead of branches, and to specify the version attribute in the pyproject.toml.
  3. Validate that the release should work by opening a 'DO NOT MERGE' PR into release (example).
  4. If this passes then you should manually trigger the release workflow, passing in the name of your branch and the version number.
  5. Once this runs, review the changelog auto-generated by GitHub for the release (example) and clean it up if necessary. It can be helpful to break the changes apart by topic.
  6. Bump the version attribute in the pyproject.toml on the release branch. For instance, if you have just released 2025.4.2 then the version number in the pyproject.toml should now be 2025.4.3.dev0.
  7. Announce the new release in the Firedrake Slack, sharing a link to the release notes.

How to make a major release

  1. Make a final patch release for the current major version (e.g. release 2025.4.3 before releasing 2025.10.0). This should pin dependencies that are known to having breaking changes between release and main branches (e.g. FIAT, UFL) (example). This should be done to make sure that users are still able to install the older version for at least a little longer. To do this follow the procedure for making patch releases described above.
  2. Coordinate the releases of the upstream packages that use branches (e.g. FIAT, UFL).
  3. Create a branch off release and merge in main (here called myusername/merge-main). Make sure that any main-specific bits of information are not carried through. In particular make sure to check pyproject.toml. Note that the documentation may fail to build as it will be using an older container.
  4. At the same time bump the versions of dependencies that have just been updated (e.g. FIAT, UFL, pyadjoint). Also bump the PETSc version.
  5. Merge (via a PR) myusername/merge-main into release.
  6. Follow the steps to make a patch release.
  7. Bump the version attribute in the pyproject.toml on the main branch. For instance, if you have just released 2025.10.0 then the version number in the pyproject.toml should now be 2025.11.0.dev0 (just choose the next possible major version number, don't worry about the specific release date).
  8. Merge release into main. This is helpful to do immediately as care is needed to resolve the conflicts that took place during the release.