diff --git a/RELEASE.md b/RELEASE.md index 2956c1b43fe..522d45bac1f 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -6,11 +6,13 @@ Check out all of the FEniCSx components on the `release` branch. Check that all CIs on `main` are running green. -Check that the `main` documentation looks reasonable https://docs.fenicsproject.org. +Check that the `main` documentation looks reasonable at +https://docs.fenicsproject.org. -The release proceeds in a bottom up manner (Basix, UFL, FFCx, DOLFINx). -GitHub Releases and pypa packages cannot be deleted and should be made a number -of days after the creation of git tags so that errors can be fixed. +The release proceeds in a bottom up manner (Basix, UFL, FFCx, DOLFINx). pypa +packages cannot be deleted and should be made a number of days after the +creation of git tags so that errors can be fixed. GitHub releases can have their +version notes updated, and can be deleted and remade on new tags (not recommended). The release process consists of the following steps: @@ -19,7 +21,8 @@ The release process consists of the following steps: 3. Make git tags on the tip of `release`. 4. Organise production of release artifacts. 5. Update version numbers on `main`. -6. Make GitHub and pypa releases (permanent!). +6. Make GitHub releases (not permanent) +7. pypa releases (permanent!). ## Version bumping @@ -34,21 +37,20 @@ UFL still runs on the year-based release scheme. git pull git checkout release - git merge --no-commit main - git checkout --theirs main . - git diff main - -2. Update version numbers, e.g. - - python3 update_versions.py -v 0.5.0 + git merge --no-commit origin/main + git checkout --theirs origin/main . # files deleted on `main` must be manually `git add`ed + git diff origin/main -3. Inspect automatic version updates. +2. Update version numbers in `pyproject.toml`, `python/pyproject.toml`, + `CMakeLists.txt` and `cpp/CMakeLists.txt`. - git diff +4. In `pyproject.toml` update the `fenics-ufl` optional dependency version. On + `main` this is often pointing at the git repo, it needs to be changed to a + version bound e.g. `>=2024.1.0,<2024.2.0`. -4. Commit and push. +5. Commit and push. -5. Check `git diff origin/main` for obvious errors. +6. Check `git diff origin/main` for obvious errors. ### UFL version bump @@ -57,7 +59,7 @@ UFL still runs on the year-based release scheme. git pull git checkout release git merge --no-commit main - git checkout --theirs main . + git checkout --theirs origin/main . # files deleted on `main` must be manually git `add`ed git diff main 2. Update the version number in `pyproject.toml`, e.g. `2022.2.0`. @@ -72,18 +74,20 @@ UFL still runs on the year-based release scheme. git pull git checkout release - git merge --no-commit main - git checkout --theirs main . - git diff main + git merge --no-commit origin/main + git checkout --theirs origin/main . # files deleted on `main` must be manually git `add`ed + git diff origin/main 2. Update the version number in `pyproject.toml`, e.g. `0.5.0`. -3. Update the dependency versions for `fenics-basix` and `fenics-ufl` in `pyproject.toml`. +3. Update the dependency versions for `fenics-basix` and `fenics-ufl` in + `pyproject.toml`. -4. If necessary, update the version number in `cmake/CMakeLists.txt`, e.g. `0.5.0`. +4. If necessary, update the version number in `cmake/CMakeLists.txt`, e.g. + `0.5.0`. -5. Update the version number macros in `ffcx/codegeneration/ufcx.h`. Typically this - should match the Python version number. Remember to change the +5. Update the version number macros in `ffcx/codegeneration/ufcx.h`. Typically + this should match the Python version number. Remember to change the `UFCX_VERSION_RELEASE` to `1`. 6. Commit and push. @@ -96,25 +100,23 @@ UFL still runs on the year-based release scheme. git pull git checkout release - git merge --no-commit main - git checkout --theirs main . + git merge --no-commit origin/main + git checkout --theirs origin/main . # files deleted on `main` must be manually git `add`ed git diff origin/main -2. In `cpp/CMakeLists.txt` change the version number near the top of the file, - e.g. `0.5.0`. +2. In `cpp/CMakeLists.txt` change the version number e.g. `0.5.0`. -3. In `cpp/CMakeLists.txt` check the `find_package(ufcx)` and - `find_package(UFCx)` calls. If the DOLFINx and UFCx versions match then - there is no need to change anything here. However, if they don't match, you - need to manually specify the appropriate UFCx version. +3. In `cpp/CMakeLists.txt` change the version number in the + `find_package(ufcx)` and `find_package(UFCx)` calls. 4. In `python/pyproject.toml` update the version to e.g. `0.5.0` and update the dependency versions for `fenics-ffcx` and `fenics-ufl`. -5. In `CITATION.md` change the line starting `version:` to e.g. `version: 0.5.0` and - update the line starting `date-released:` to e.g. `date-released: 2022-03-14`. +5. In `CITATION.md` update the version number `version: 0.5.0` and the release + date `date-released: 2022-03-14`. -6. In `.github/ISSUE_TEMPLATE/bug_report.yml` add a new option to the version dropdown. +6. In `.github/ISSUE_TEMPLATE/bug_report.yml` add a new option to the version + numbers. 7. Commit and push. @@ -126,7 +128,8 @@ Although lengthy, integration testing is highly effective at discovering issues and mistakes before they reach tagged versions. At each of the following links run the GitHub Action Workflow manually using -the `release` branch in all fields. *Only proceed to tagging once all tests pass.* +the `release` branch in all fields, including the . *Only proceed to tagging +once all tests pass.* Basix with FFCx: https://github.com/FEniCS/basix/actions/workflows/ffcx-tests.yml @@ -138,6 +141,7 @@ FFCx with DOLFINx: https://github.com/FEniCS/ffcx/actions/workflows/dolfinx-test Full stack: https://github.com/FEniCS/dolfinx/actions/workflows/ccpp.yml + ## Tagging Make appropriate version tags in each repository. UFL does not use the `v` prefix. @@ -154,7 +158,7 @@ of tags. You will need to manually update the `README.md`. ### Docker containers -First create tagged development and test environment images: +First create tagged development and test environment images, e.g. `v0.5.0`: https://github.com/FEniCS/dolfinx/actions/workflows/docker-dev-test-env.yml @@ -163,8 +167,8 @@ development image: https://github.com/FEniCS/dolfinx/actions/workflows/docker-end-user.yml -The tag prefix should be the same as the DOLFINx tag e.g. `v0.5.0`. -Git refs should be appropriate tags for each component. +The tag prefix should be the same as the DOLFINx tag e.g. `v0.5.0`. Git refs +should be appropriate tags for each component. Tagged Docker images will be pushed to Dockerhub and GitHub. @@ -173,6 +177,8 @@ Tagged Docker images will be pushed to Dockerhub and GitHub. Use the *Docker update stable* tag workflow to update/link `:stable` to e.g. `v0.5.0`. +https://github.com/FEniCS/dolfinx/actions/workflows/docker-update-stable.yml + ### pypa Wheels can be made using the following actions: @@ -194,8 +200,15 @@ process at this time. ### Mistakes -Aside from version numbering changes, it is easier to merge changes onto `main` -and then cherry-pick or merge back onto `release`. +If something doesn't work, or other issues/bugs are identified during the +release process you can either: + +1. Make changes on `main` via the usual PR workflow, then `git cherry-pick` or + `git merge` the commit back onto `release`. + +2. Manually make commits on the `release` branch. + +If you want the change to be reflected on `main` long term 1. is preferred. If a mistake is noticed soon after making a tag then you can delete the tag and recreate it. It is also possible to recreate GitHub releases. After pypa @@ -218,20 +231,21 @@ https://github.com/FEniCS/dolfinx/releases/new ## Post-release -Check for any changes on `release` that should be ported back onto `main`. +Check for any changes on `release` that should be cherry-picked back onto +`main` via a PR. git checkout main git diff release -Bump the version numbers on the `main` branch. +Bump the version numbers on the `main` branch via a PR. ## Bug fix patches -Bug fix patches can be made by cherry picking commits off of `main` and bumping -the minor version number. Remember to run the DOLFINx integration tests on a -proposed set of tags as it is easy to make an error. +Bug fix versions e.g. `v0.5.1` can be made by cherry picking commits off of +`main` and bumping the minor version number. Remember to run the DOLFINx +integration tests on a proposed set of tags as it is easy to make an error. -### Ubuntu +### Debian/Ubuntu Contact Drew Parsons.