Updates and clarifications in release notes (#3160)

* Updates and clarifications in release notes.

* Update RELEASE.md

* Update RELEASE.md

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.