diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 0000000..4df4447 --- /dev/null +++ b/MAINTAINERS.md @@ -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