Skip to content

Latest commit

 

History

History
180 lines (135 loc) · 8.89 KB

RELEASING.md

File metadata and controls

180 lines (135 loc) · 8.89 KB
Raw

Release Procedures

These notes are meant for a maintainer to create official releases.

In 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.)

Core C library

Some minor bookkeeping updates are needed when releasing a new version of the core library.

The version number must be updated in

  • include/ceed.h
  • ceed.pc.template
  • Doxyfile
  • CITATION.cff

Additionally, the release notes in doc/sphinx/source/releasenotes.md 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. The "Current Main" heading needs to be named for the release.

Use 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.

Quality control and good citizenry

  1. If making a minor release, check for API and ABI changes that could break semantic versioning. The 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).

  2. 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 tagging a libCEED release.

  3. Update and test all the language bindings (see below) within the branch.

  4. Check that spack install libceed@develop works prior to tagging. The Spack libceed/package.py file should be updated immediately after tagging a release.

Tagging and releasing on GitHub

  1. Confirm all the steps above, including all language bindings.
  2. git commit -am'libCEED 0.8.1' More frequently, this is amending the commit message on an in-progress commit, after rebasing if applicable on latest main.
  3. git push updates the PR holding release; opportunity for others to review
  4. git switch main && git merge --ff-only HEAD@{1} fast-forward merge into main
  5. git tag --sign -m'libCEED 0.8.1'
  6. git push origin main v0.8.1
  7. Draft a new release on GitHub, using a few sentences gathered from the release notes.
  8. Submit a PR to Spack.
  9. Publish Julia, Python, and Rust packages.

Archive Users Manual on Zenodo

Generate the PDF using make doc-latexpdf, click "New version" on the Zenodo record and upload. Update author info if applicable (new authors, or existing authors changing institutions). Make a new PR to update the version number and DOI in README.rst and doc/bib/references.bib.

Julia

libCEED's Julia interface (LibCEED.jl) has two components:

  • LibCEED.jl, the user-facing package that contains the Julia interface.
  • libCEED_jll, a binary wrapper package ("jll package") that contains prebuilt binaries of the libCEED library for various architectures.

When there is a new release of libCEED, both of these components need to be updated. First, libCEED_jll is updated, and then LibCEED.jl.

Updating libCEED_jll

The binary wrapper package libCEED_jll is updated by making a pull request against Yggdrasil, the Julia community build tree. In 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:

diff --git a/L/libCEED/build_tarballs.jl b/L/libCEED/build_tarballs.jl
--- a/L/libCEED/build_tarballs.jl
+++ b/L/libCEED/build_tarballs.jl
@@ -3,11 +3,11 @@
 using BinaryBuilder, Pkg

 name = "libCEED"
-version = v"0.7.0"
+version = v"0.8.0"

 # Collection of sources required to complete build
 sources = [
-    GitSource("https://github.com/CEED/libCEED.git", "06988bf74cc6ac18eacafe7930f080803395ba29")
+    GitSource("https://github.com/CEED/libCEED.git", "e8f234590eddcce2220edb1d6e979af7a3c35f82")
 ]

After 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.

Updating LibCEED.jl

After the binary wrapper package libCEED_jll has been updated, we are ready to update the main Julia interface LibCEED.jl. This requires updating the file julia/LibCEED.jl/Project.toml in the libCEED repository. The version number should be incremented, and the dependency on the updated version of libCEED_jll should be listed:

diff --git a/julia/LibCEED.jl/Project.toml b/julia/LibCEED.jl/Project.toml
--- a/julia/LibCEED.jl/Project.toml
+++ b/julia/LibCEED.jl/Project.toml
@@ -1,7 +1,7 @@
 name = "LibCEED"
 uuid = "2cd74e05-b976-4426-91fa-5f1011f8952b"
-version = "0.1.0"
+version = "0.1.1"

 [deps]
 CEnum = "fa961155-64e5-5f13-b03f-caf6b980ea82"
@@ -26,4 +26,4 @@ Cassette = "0.3"
 Requires = "1"
 StaticArrays = "0.12"
 UnsafeArrays = "1"
-libCEED_jll = "0.7"
+libCEED_jll = "0.8"

Make sure that the generated Julia bindings have been updated

$ cd julia/LibCEED.jl/gen
$ julia --project=../../.. -e 'include("generator.jl"); generate_ceed_bindings("../../..")'

Once 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:

@JuliaRegistrator register branch=main subdir=julia/LibCEED.jl

At this point, the bot should create a PR against the general Julia registry, which should be merged automatically after a short delay.

Moving development tests to release tests

LibCEED.jl has both development and release unit tests. The release tests are run both with the current build of libCEED, and with the most recent release of libCEED_jll. The 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.

Upon 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. The 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.

Python

The Python package gets its version from ceed.pc.template so there are no file modifications necessary.

  1. 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).
  2. CI publishes wheels on v** tags, assuming tests pass.

Reminder about manual publishing (not needed with CI)

  1. Create a ~/.pypirc with entries for testpypi (https://test.pypi.org/legacy/) and the real pypi.
  2. Upload to testpypi using
$ twine upload --repository testpypi wheelhouse/libceed-0.8-cp39-cp39-manylinux2010_x86_64.whl
  1. Test installing on another machine/in a virtualenv:
$ pip install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple libceed

The --extra-index-url argument allows dependencies like cffi and numpy from being fetched from the non-test repository. 4. Do it live:

$ twine upload --repository pypi wheelhouse/libceed-0.8-cp39-cp39-manylinux2010_x86_64.whl

Note that this cannot be amended.

Rust

The Rust crates for libCEED are split into

  1. 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)
  2. libceed containing the safe and idiomatic Rust bindings.

We currently apply the same version number across both of these crates. Version 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.

$ cargo release --no-tag --no-push --no-publish 0.12.0 --execute

After doing this,

  1. cargo package --list --package libceed-sys and --package libceed to see that the file list makes sense.
  2. cargo release to build crates locally (handling dependencies between creates in the workspace)
  3. cargo release publish --execute to publish the crates to https://crates.io