Releasing guide

RELEASING.md

@@ -1,16 +1,38 @@
 # Release Procedures
 
-## Core library
+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.)
 
-Some minor bookkeeping updates are needed when releasing a new verision of the core library.
+## 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/ceed.h`
 * `ceed.pc.template`
 * `Doxyfile`
 
-Additionally, the release notes in `doc/sphinx/source/releasenotes.rst` should be updated.
+Additionally, 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.
+
+### Quality contral and good citizenry
+
+1. 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).
+
+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 taggin 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
+
+0. Confirm all the steps above, including all language bindings.
+1. `git commit -am'libCEED 0.8'`
+2. `git tag --sign -m'libCEED 0.8'`
+3. `git push`
+4. Draft a [new release on GitHub](https://github.com/CEED/libCEED/releases), using the couple sentences gathered for release notes.
+5. Submit a PR to Spack.
+6. Publish Julia, Python, and Rust packages.
 
 ## Julia
 
@@ -97,8 +119,46 @@ be tested against the most recent release of libCEED_jll. The release tests are
 
 ## Python
 
-ToDo - instructions for releasing an new Python wheel go here
+The Python package gets its version from `ceed.pc.template` so there are no file modifications necessary.
+
+1. `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`.
+2. 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.
+3. Create a `~/.pypirc` with entries for `testpypi` (`https://test.pypi.org/legacy/`) and the real `pypi`.
+4. Upload to `testpypi` using
+```console
+$ twine upload --repository testpypi wheelhouse/libceed-0.8-cp39-cp39-manylinux2010_x86_64.whl
+```
+5. Test installing on another machine/in a virtualenv:
+```console
+$ 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.
+6. Do it live:
+```console
+$ twine upload --repository pypi wheelhouse/libceed-0.8-cp39-cp39-manylinux2010_x86_64.whl
+```
+Note that this cannot be amended.
 
 ## Rust
 
-ToDo - instructions for releasing the three Rust crates go here
+The Rust crates for libCEED are split into
+1. [`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)
+2. [`libceed`](https://crates.io/crates/libceed) containing the safe and idiomatic Rust bindings.
+
+We 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.
+
+```console
+$ git grep '0\.8' -- rust/
+rust/libceed-sys/Cargo.toml:version = "0.8.0"
+rust/libceed-sys/README.md:libceed-sys = "0.8.0"
+rust/libceed-sys/build.rs:        .atleast_version("0.8")
+rust/libceed/Cargo.toml:version = "0.8.0"
+rust/libceed/Cargo.toml:libceed-sys = { version = "0.8", path = "../libceed-sys" }
+rust/libceed/README.md:libceed = "0.8.0"
+```
+
+After doing this,
+
+1. `cargo package --list` to see that the file list makes sense.
+2. `cargo package` to build crates locally
+3. `cargo publish` to publish the crates to https://crates.io