1# Release Procedures 2 3*These notes are meant for a maintainer to create official releases.* 4 5In preparing a release, create a branch to hold pre-release commits. 6We ideally want all release mechanics (for all languages) to be in one commit, which will then be tagged. 7(This will change if/when we stop synchronizing releases across all language bindings.) 8 9## Core C library 10 11Some minor bookkeeping updates are needed when releasing a new version of the core library. 12 13The version number must be updated in 14 15* `include/ceed.h` 16* `ceed.pc.template` 17* `Doxyfile` 18* `CITATION.cff` 19 20Additionally, the release notes in `doc/sphinx/source/releasenotes.md` should be updated. 21Use `git log --first-parent v0.7..` to get a sense of the pull requests that have been merged and thus might warrant emphasizing in the release notes. 22While doing this, gather a couple sentences for key features to highlight on [GitHub releases](https://github.com/CEED/libCEED/releases). 23The "Current Main" heading needs to be named for the release. 24 25Use `make doc-latexpdf` to build a PDF users manual and inspect it for missing references or formatting problems (e.g., with images that were converted to PDF). 26This contains the same content as the website, but will be archived on Zenodo. 27 28### Quality control and good citizenry 29 301. If making a minor release, check for API and ABI changes that could break [semantic versioning](https://semver.org/). 31The [ABI compliance checker](https://github.com/lvc/abi-compliance-checker) is a useful tool, as is `nm -D libceed.so` and checking for public symbols (capital letters like `T` and `D` that are not namespaced). 32 332. Double check testing on any architectures that may not be exercised in continuous integration (e.g., HPC facilities) and with users of libCEED, such as MFEM and PETSc applications. 34While unsupported changes do not prevent release, it's polite to make a PR to support the new release, and it's good for quality to test before tagging a libCEED release. 35 363. Update and test all the language bindings (see below) within the branch. 37 384. Check that `spack install libceed@develop` works prior to tagging. 39The Spack `libceed/package.py` file should be updated immediately after tagging a release. 40 41### Tagging and releasing on GitHub 42 430. Confirm all the steps above, including all language bindings. 441. `git commit -am'libCEED 0.8.1'` 45More frequently, this is amending the commit message on an in-progress commit, after rebasing if applicable on latest `main`. 462. `git push` updates the PR holding release; opportunity for others to review 473. `git switch main && git merge --ff-only HEAD@{1}` fast-forward merge into `main` 484. `git tag --sign -m'libCEED 0.8.1'` 495. `git push origin main v0.8.1` 506. Draft a [new release on GitHub](https://github.com/CEED/libCEED/releases), using a few sentences gathered from the release notes. 517. Submit a PR to Spack. 528. Publish Julia, Python, and Rust packages. 53 54### Archive Users Manual on Zenodo 55 56Generate the PDF using `make doc-latexpdf`, click "New version" on the [Zenodo record](https://zenodo.org/record/4302737) and upload. 57Update author info if applicable (new authors, or existing authors changing institutions). 58Make a new PR to update the version number and DOI in `README.rst` and `doc/bib/references.bib`. 59 60## Julia 61 62libCEED's Julia interface (LibCEED.jl) has two components: 63 64* LibCEED.jl, the user-facing package that contains the Julia interface. 65* libCEED_jll, a binary wrapper package ("jll package") that contains prebuilt binaries of the libCEED library for various architectures. 66 67When there is a new release of libCEED, both of these components need to be updated. 68First, libCEED_jll is updated, and then LibCEED.jl. 69 70### Updating libCEED_jll 71 72The binary wrapper package libCEED_jll is updated by making a pull request against [Yggdrasil](https://github.com/JuliaPackaging/Yggdrasil), the Julia community build tree. 73In this PR, the file `L/libCEED/build_tarballs.jl` should be changed to update version number and change the hash of the libCEED commit to use to build the binaries, similar to the following diff: 74```diff 75diff --git a/L/libCEED/build_tarballs.jl b/L/libCEED/build_tarballs.jl 76--- a/L/libCEED/build_tarballs.jl 77+++ b/L/libCEED/build_tarballs.jl 78@@ -3,11 +3,11 @@ 79 using BinaryBuilder, Pkg 80 81 name = "libCEED" 82-version = v"0.7.0" 83+version = v"0.8.0" 84 85 # Collection of sources required to complete build 86 sources = [ 87- GitSource("https://github.com/CEED/libCEED.git", "06988bf74cc6ac18eacafe7930f080803395ba29") 88+ GitSource("https://github.com/CEED/libCEED.git", "e8f234590eddcce2220edb1d6e979af7a3c35f82") 89 ] 90``` 91After the PR is merged into Yggdrasil, the new version of libCEED_jll will automatically be registered, and then we can proceed to update LibCEED.jl. 92 93### Updating LibCEED.jl 94 95After the binary wrapper package libCEED_jll has been updated, we are ready to update the main Julia interface LibCEED.jl. 96This requires updating the file `julia/LibCEED.jl/Project.toml` in the libCEED repository. 97The version number should be incremented, and the dependency on the updated version of `libCEED_jll` should be listed: 98```diff 99diff --git a/julia/LibCEED.jl/Project.toml b/julia/LibCEED.jl/Project.toml 100--- a/julia/LibCEED.jl/Project.toml 101+++ b/julia/LibCEED.jl/Project.toml 102@@ -1,7 +1,7 @@ 103 name = "LibCEED" 104 uuid = "2cd74e05-b976-4426-91fa-5f1011f8952b" 105-version = "0.1.0" 106+version = "0.1.1" 107 108 [deps] 109 CEnum = "fa961155-64e5-5f13-b03f-caf6b980ea82" 110@@ -26,4 +26,4 @@ Cassette = "0.3" 111 Requires = "1" 112 StaticArrays = "0.12" 113 UnsafeArrays = "1" 114-libCEED_jll = "0.7" 115+libCEED_jll = "0.8" 116``` 117 118Make sure that the generated Julia bindings have been updated 119```console 120$ cd julia/LibCEED.jl/gen 121$ julia --project=../../.. -e 'include("generator.jl"); generate_ceed_bindings("../../..")' 122``` 123Once this change is merged into libCEED's `main` branch, the updated package version can be registered using the GitHub registrator bot by commenting on the commit: 124 125> @JuliaRegistrator register branch=main subdir=julia/LibCEED.jl 126 127At this point, the bot should create a PR against the [general Julia registry](https://github.com/JuliaRegistries/General), which should be merged automatically after a short delay. 128 129### Moving development tests to release tests 130 131LibCEED.jl has both _development_ and _release_ unit tests. 132The _release_ tests are run both with the current build of libCEED, and with the most recent release of libCEED_jll. 133The _development_ tests may use features which were not available in the most recent release, and so they are only run with the current build of libCEED. 134 135Upon release, the development tests may be moved to the release tests, so that these features will be tested against the most recent release of libCEED_jll. 136The release tests are found in the file `julia/LibCEED.jl/test/runtests.jl` and the development tests are found in `julia/LibCEED.jl/test/rundevtests.jl`. 137 138## Python 139 140The Python package gets its version from `ceed.pc.template` so there are no file modifications necessary. 141 1421. CI builds and tests wheels when a pull request has the `release preparation` label. One can also use `cibuildwheel --only cp310-manylinux_x86_64` to build and test wheels locally (inside a container). 1432. CI publishes wheels on `v**` tags, assuming tests pass. 144 145### Reminder about manual publishing (not needed with CI) 146 1471. Create a `~/.pypirc` with entries for `testpypi` (`https://test.pypi.org/legacy/`) and the real `pypi`. 1482. Upload to `testpypi` using 149```console 150$ twine upload --repository testpypi wheelhouse/libceed-0.8-cp39-cp39-manylinux2010_x86_64.whl 151``` 1523. Test installing on another machine/in a virtualenv: 153```console 154$ pip install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple libceed 155``` 156The `--extra-index-url` argument allows dependencies like `cffi` and `numpy` from being fetched from the non-test repository. 1574. Do it live: 158```console 159$ twine upload --repository pypi wheelhouse/libceed-0.8-cp39-cp39-manylinux2010_x86_64.whl 160``` 161Note that this cannot be amended. 162 163## Rust 164 165The Rust crates for libCEED are split into 1661. [`libceed-sys`](https://crates.io/crates/libceed-sys), which handles building/finding the `libceed.so` or `libceed.a` library and providing unsafe Rust bindings (one to one with the C interface, using C FFI datatypes) 1672. [`libceed`](https://crates.io/crates/libceed) containing the safe and idiomatic Rust bindings. 168 169We currently apply the same version number across both of these crates. 170Version numbers are automatically updated using the following, which creates a new commit with the version updates. You can squash that commit into the commit with version updates for the rest of the package. 171 172```console 173$ cargo release --no-tag --no-push --no-publish 0.12.0 --execute 174``` 175 176After doing this, 177 1781. `cargo package --list --package libceed-sys` and `--package libceed` to see that the file list makes sense. 1792. `cargo release` to build crates locally (handling dependencies between creates in the workspace) 1803. `cargo release publish --execute` to publish the crates to https://crates.io 181