chore: Add MAINTAINERS.md with release process

This commit is contained in:
Duncan Dean 2023-05-03 16:07:41 +02:00
parent fc8aa55004
commit 69285e7c06
No known key found for this signature in database

77
MAINTAINERS.md Normal file
View file

@ -0,0 +1,77 @@
# Guide for maintainers of LNDK
## Release process
We prefer having the entire lifecycle of the release process happen within GitHub actions so that there are no "loose ends"
or inconsistencies between releases based on local environments.
### Prerequisites
```shell
cargo install --locked cargo-dist cargo-release
```
### Use of `cargo-dist` in this project
This project uses [cargo-dist] for automating the release process as much as possible.
Release builds happen via GitHub Actions and the workflow can be seen [here](.github/workflows/release.yml). The file is generated
by `cargo-dist` and should generally not be modified manually, but we've included an intermediate signing step with cosign, until
`cargo-dist` supports it upstream at some stage.
### Setting up signing of release artifacts
We use [Sigstore]'s [Cosign] utility to have GitHub Actions sign a release `checksum.txt` file with a key generated as a GitHub Secret
so that only GitHub Actions can sign.
The key is generated by the lead maintainer (carlaKC) with the `cosign` CLI as follows:
```shell
cosign generate-key-pair github://carlaKC/lndk
````
NOTE:
* A password for the key MUST be provided.
* You must have a GitHub Personal Access Token in the `GITHUB_TOKEN` environment variable locally.
A [fine-grained token] with the "Secrets" permission under "Repository permissions"
set to "Read and write" access is sufficient. The token can be revoked after generating the key-pair.
An output similar to below indicates a key was successfully generated:
```
Password written to COSIGN_PASSWORD github actions secret
Private key written to COSIGN_PRIVATE_KEY github actions secret
Public key written to COSIGN_PUBLIC_KEY github actions secret
Public key also written to cosign.pub
```
The `cosign.pub` should be commited to the project's root along with its PGP signature (`cosign.pub.asc`) manually signed by carlaKC.
This allows users to verify the key is authentic. Unfortunately, with a fulle GitHub CI actions process, keyless signing with GitHub
OIDC is not yet supported. We may consider this in the future along with compatibility with Sigstore's Fulcio for proper code-signing
when generating a single bundle for signing multiple blobs is possible.
When the release process actually builds the release artifacts, a `checksums.txt` file is created with the SHA256 digests of
all the artifacts. Then `cosign` signs `checksums.txt` with the private key generated above, resulting in a `cosign.bundle` which can
be used to verify `checksums.txt`:
```shell
cosign verify-blob --key cosign.pub --bundle cosign.bundle checksums.txt
```
### On day of new release
We'll be using `cargo-release` to simplify the process.
A single command is run for a new release tagged `v0.0.1` for example:
```shell
cargo release --no-publish --execute --tag 0.0.11
```
NOTE: The `v` prefix is excluded in the command about, but the git tag will include it.
The command above does quite a lot for us. It generates the changelog with `git-cliff`,
bumps the project's version number, commits thos changes and atomically pushes the changes
and tag.
[sigstore]: https://docs.sigstore.dev/
[cosign]: https://docs.sigstore.dev/cosign/overview/
[cargo-dist]: https://opensource.axo.dev/cargo-dist
[fine-grained token]: https://github.com/settings/personal-access-tokens/new