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. We ideally want all release mechanics (for all languages) to be in one commit, which will then be tagged. (This will change if/when we stop synchronizing releases across all language bindings.) 6 7## Core C library 8 9Some minor bookkeeping updates are needed when releasing a new version of the core library. 10 11The version number must be updated in 12 13* `include/ceed/ceed.h` 14* `ceed.pc.template` 15* `Doxyfile` 16* `CITATION.cff` 17 18as well as `include/ceed/ceed.h` (`CEED_VERSION_MAJOR`, `CEED_VERSION_MINOR`). 19 20Additionally, the release notes in `doc/sphinx/source/releasenotes.rst` should be updated. Use `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. While doing this, gather a couple sentences for key features to highlight on [GitHub releases](https://github.com/CEED/libCEED/releases). The "Current Main" heading needs to be named for the release. 21 22Use `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). This contains the same content as the website, but will be archived on Zenodo. 23 24### Quality control and good citizenry 25 261. If making a minor release, check for API and ABI changes that could break [semantic versioning](https://semver.org/). The [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). 27 282. 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. While 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 taggin a libCEED release. 29 303. Update and test all the language bindings (see below) within the branch. 31 324. Check that `spack install libceed@develop` works prior to tagging. The Spack `libceed/package.py` file should be updated immediately after tagging a release. 33 34### Tagging and releasing on GitHub 35 360. Confirm all the steps above, including all language bindings. 371. `git commit -am'libCEED 0.8.1'` 38More frequently, this is amending the commit message on an in-progress commit, after rebasing if applicable on latest `main`. 392. `git push` updates the PR holding release; opportunity for others to review 403. `git switch main && git merge --ff-only HEAD@{1}` fast-forward merge into `main` 414. `git tag --sign -m'libCEED 0.8.1'` 425. `git push origin main v0.8.1` 436. Draft a [new release on GitHub](https://github.com/CEED/libCEED/releases), using a few sentences gathered from the release notes. 447. Submit a PR to Spack. 458. Publish Julia, Python, and Rust packages. 46 47### Archive Users Manual on Zenodo 48 49Generate the PDF using `make doc-latexpdf`, click "New version" on the [Zenodo 50record](https://zenodo.org/record/4302737) and upload. Update author info if applicable (new 51authors, or existing authors changing institutions). Make a new PR to update the version 52number and DOI in `README.rst` and `doc/bib/references.bib`. 53 54## Julia 55 56libCEED's Julia interface (LibCEED.jl) has two components: 57 58* LibCEED.jl, the user-facing package that contains the Julia interface. 59* libCEED_jll, a binary wrapper package ("jll package") that contains prebuilt binaries of the 60 libCEED library for various architectures. 61 62When there is a new release of libCEED, both of these components need to be updated. First, 63libCEED_jll is updated, and then LibCEED.jl. 64 65### Updating libCEED_jll 66 67The binary wrapper package libCEED_jll is updated by making a pull request against 68[Yggdrasil](https://github.com/JuliaPackaging/Yggdrasil), the Julia community build tree. In this 69PR, the file `L/libCEED/build_tarballs.jl` should be changed to update version number and change the 70hash of the libCEED commit to use to build the binaries, similar to the following diff: 71```diff 72diff --git a/L/libCEED/build_tarballs.jl b/L/libCEED/build_tarballs.jl 73--- a/L/libCEED/build_tarballs.jl 74+++ b/L/libCEED/build_tarballs.jl 75@@ -3,11 +3,11 @@ 76 using BinaryBuilder, Pkg 77 78 name = "libCEED" 79-version = v"0.7.0" 80+version = v"0.8.0" 81 82 # Collection of sources required to complete build 83 sources = [ 84- GitSource("https://github.com/CEED/libCEED.git", "06988bf74cc6ac18eacafe7930f080803395ba29") 85+ GitSource("https://github.com/CEED/libCEED.git", "e8f234590eddcce2220edb1d6e979af7a3c35f82") 86 ] 87``` 88After the PR is merged into Yggdrasil, the new version of libCEED_jll will automatically be 89registered, and then we can proceed to update LibCEED.jl. 90 91### Updating LibCEED.jl 92 93After the binary wrapper package libCEED_jll has been updated, we are ready to update the main Julia 94interface LibCEED.jl. This requires updating the file `julia/LibCEED.jl/Project.toml` in the libCEED 95repository. The version number should be incremented, and the dependency on the updated version of 96libCEED_jll should be listed: 97```diff 98diff --git a/julia/LibCEED.jl/Project.toml b/julia/LibCEED.jl/Project.toml 99--- a/julia/LibCEED.jl/Project.toml 100+++ b/julia/LibCEED.jl/Project.toml 101@@ -1,7 +1,7 @@ 102 name = "LibCEED" 103 uuid = "2cd74e05-b976-4426-91fa-5f1011f8952b" 104-version = "0.1.0" 105+version = "0.1.1" 106 107 [deps] 108 CEnum = "fa961155-64e5-5f13-b03f-caf6b980ea82" 109@@ -26,4 +26,4 @@ Cassette = "0.3" 110 Requires = "1" 111 StaticArrays = "0.12" 112 UnsafeArrays = "1" 113-libCEED_jll = "0.7" 114+libCEED_jll = "0.8" 115``` 116Once this change is merged into libCEED's `main` branch, the updated package version can be 117registered using the GitHub registrator bot by commenting on the commit: 118 119> @JuliaRegistrator register branch=main subdir=julia/LibCEED.jl 120 121At this point, the bot should create a PR against the [general Julia 122registry](https://github.com/JuliaRegistries/General), which should be merged automatically after a 123short delay. 124 125### Moving development tests to release tests 126 127LibCEED.jl has both _development_ and _release_ unit tests. The _release_ tests are run both with 128the current build of libCEED, and with the most recent release of libCEED_jll. The _development_ 129tests may use features which were not available in the most recent release, and so they are only run 130with the current build of libCEED. 131 132Upon release, the development tests may be moved to the release tests, so that these features will 133be tested against the most recent release of libCEED_jll. The release tests are found in the file 134`julia/LibCEED.jl/test/runtests.jl` and the development tests are found in 135`julia/LibCEED.jl/test/rundevtests.jl`. 136 137## Python 138 139The Python package gets its version from `ceed.pc.template` so there are no file modifications necessary. 140 1411. `make wheel` builds and tests the wheels using Docker. See the [manylinux repo](https://github.com/pypa/manylinux) for source and usage inforamtion. If this succeeds, the completed wheels are in `wheelhouse/libceed-0.8-cp39-cp39-manylinux2010_x86_64.whl`. 1422. Manually test one or more of the wheels by creating a virtualenv and using `pip install wheelhouse/libceed-0.8-cp39-cp39-manylinux2010_x86_64.whl`, then `python -c 'import libceed'` or otherwise running tests. 1433. Create a `~/.pypirc` with entries for `testpypi` (`https://test.pypi.org/legacy/`) and the real `pypi`. 1444. Upload to `testpypi` using 145```console 146$ twine upload --repository testpypi wheelhouse/libceed-0.8-cp39-cp39-manylinux2010_x86_64.whl 147``` 1485. Test installing on another machine/in a virtualenv: 149```console 150$ pip install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple libceed 151``` 152The `--extra-index-url` argument allows dependencies like `cffi` and `numpy` from being fetched from the non-test repository. 1536. Do it live: 154```console 155$ twine upload --repository pypi wheelhouse/libceed-0.8-cp39-cp39-manylinux2010_x86_64.whl 156``` 157Note that this cannot be amended. 158 159## Rust 160 161The Rust crates for libCEED are split into 1621. [`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) 1632. [`libceed`](https://crates.io/crates/libceed) containing the safe and idiomatic Rust bindings. 164 165We currently apply the same version number across both of these crates. There are some tests for version strings matching, but in short, one needs to update the following locations. 166 167```console 168$ git grep '0\.8' -- rust/ 169rust/libceed-sys/Cargo.toml:version = "0.8.0" 170rust/libceed-sys/README.md:libceed-sys = "0.8.0" 171rust/libceed-sys/build.rs: .atleast_version("0.8") 172rust/libceed/Cargo.toml:version = "0.8.0" 173rust/libceed/Cargo.toml:libceed-sys = { version = "0.8", path = "../libceed-sys" } 174rust/libceed/README.md:libceed = "0.8.0" 175``` 176 177After doing this, 178 1791. `cargo package --list` to see that the file list makes sense. 1802. `cargo package` to build crates locally 1813. `cargo publish` to publish the crates to https://crates.io 182