Back to MusePages

Historic Atlas — A release you can name

The original prompt, shown in full as plain text.

Prompt

# SPEC: Releases

Status: draft. Part of [SPEC.md](../SPEC.md).

## Purpose

Mark named releases in the source tree, so that a host runs a known,
reproducible version of the application instead of whatever happens to be
checked out.

## Requirements

- A release is an annotated git tag on a commit of `main`.
- Every release has a version and notes saying what changed since the
  previous release.
- A release is created by one script, `tools/release.sh`, which refuses to
  create a release that is not reproducible: the working tree must be clean,
  the branch `main` and in sync with its remote, and the work item check
  must pass.
- A host can tell which release it runs.

## Decisions

- **Version scheme:** semantic versioning, `MAJOR.MINOR.PATCH`. While
  there is no public version, `MAJOR` is 0 and a breaking change raises
  `MINOR`. The first release is `0.1.0`.
- **Tag name:** the version with a leading `v`, for example `v0.1.0`. Only
  tags of this form are releases; the script compares them with a version
  sort and accepts only a version greater than the latest one.
- **Notes:** the message of the annotated tag lists the subjects of the
  commits since the previous release, one per line, which already carry the
  work item IDs (see [SPEC-work-tracking.md](SPEC-work-tracking.md)). There
  is no separate changelog file.
- **Signing:** the tag is signed (`git tag -s`) when `user.signingkey` is
  configured, and only annotated otherwise.
- **Creating a release:** `tools/release.sh <version>` creates the tag
  locally and prints it; `tools/release.sh <version> --push` also pushes the
  tag. Without the push option nothing leaves the machine.
- **Which release a host runs:** a host runs the checkout from which
  `deploy/deploy.sh` was run (see
  [SPEC-deployment.md](SPEC-deployment.md)). Deploying a release means
  checking out its tag there first.
- **Images:** introduced in [AVARC-31](../tasks/finished/TASK-image-builds.md),
  split by module in [AVARC-52](../tasks/finished/TASK-per-module-builds.md). One
  GitHub Actions workflow per module (`ci-backend.yml`, `ci-frontend.yml`,
  `ci-ingress.yml`, `ci-keycloak.yml`) builds and tests that module
  (`./mvnw -Pwith-docker -pl avarc-server-<module> verify`, which builds its
  image) on pushes to `main` and on pull requests that change its directory
  or the shared build files (the root `pom.xml`, the Maven wrapper,
  `tools/publish-images.sh` and the workflow files involved), except
  changes of Markdown files only. The modules do not depend on each other.
  All of them call the reusable workflow `build-module.yml`, which holds the
  steps. A push publishes only the image of the module it built; pull
  requests only build. A release tag is built by the workflow `ci-release.yml`,
  which runs the same steps for all four modules, so a release names a
  consistent set. The publishing logic is the script
  `tools/publish-images.sh`, not the workflow.
  - **Notification:** after a successful build and publishing of a push to
    `main` of this repository (not a pull request, fork or release tag), a
    separate job of the module workflow posts one message with the commit
    and the module name to a chat
    channel through an incoming webhook, the only thing it needs being one
    secret. A listener of the deployment side reads the message as a hint
    only: it checks the registry for new `snapshot` images before it updates
    stage, so a forged message cannot deploy anything that was not
    published. The notification is best effort: without the secret it is
    skipped, and a failure only shows as a warning, so it never fails the
    workflow. The chat server, the listener and how stage is updated are
    not part of this repository.
  - **Registry:** the GitHub Container Registry, namespace
    `ghcr.io/avarcorg`, images `avarc-backend`,
    `avarc-frontend`, `avarc-ingress` and `avarc-keycloak`. The packages are public (the source is), so a host
    pulls without logging in. The workflow logs in
    with its own token, which only pushes may use. The images carry the `org.opencontainers.image.source`
    label of the repository, which links the packages to it.
  - **Tags:** a push to `main` publishes the moving tag `snapshot` and the
    tag `sha-<first seven characters of the commit>` of the images built
    from that commit; the others keep their own latest `snapshot`. A release
    tag `vX.Y.Z` publishes `X.Y.Z` and `latest` of all four. The version in the POMs is not
    the published version: the build tags the images with it locally and
    the script retags them.
  - **Versions and caches:** the Java and Node versions are constants in
    the reusable workflow's `env`; a step fails the build when they differ from the
    POMs. Cached between runs: the Maven repository and the wrapper's Maven
    distribution (by `actions/setup-java`) and npm's downloads (the Node
    container keeps them in a host directory, see `docker-node.sh`). The
    Docker images that the build pulls (the buildpack builders, the Node
    image, the Keycloak base image) and the downloads inside a `pack` build (JRE, Node) are not
    cached: the cache action for Docker images that was tried no longer
    works with GitHub's cache service.
  - **Cleaning images:** introduced in [AVARC-40](../tasks/finished/TASK-clean-images.md).
    The workflow "Clean images" (`.github/workflows/clean-images.yml`) runs
    weekly and on demand with the permission `packages: write` only (the
    four packages are linked to the repository). For each of the four
    images it deletes the versions that carry only `sha-<commit>` tags and
    are older than 30 days, and the untagged versions older than one day
    that no remaining version references (the platform manifests of a
    multi-platform image are found by reading the manifest of each remaining
    version). The newest 5 versions of each image are never deleted. A
    version tagged `snapshot`, `latest` or `X.Y.Z` is never deleted, so
    every release stays pullable. Hosts name `snapshot` or a release tag in
    their secrets file, never a bare `sha-` tag. The days, the number of
    versions to keep and a dry run (lists, deletes nothing) are inputs of
    the manual run.
  - **Cleaning workflow runs:** introduced in [AVARC-39](../tasks/finished/TASK-clean-action-runs.md).
    The workflow "Clean workflow runs" (`.github/workflows/clean-runs.yml`)
    runs weekly and on demand with the permission `actions: write` only. It
    deletes finished runs older than 30 days, but keeps the latest 5 runs of
    every workflow; queued and running runs are never touched. Both values
    and a dry run (lists, deletes nothing) are inputs of the manual run.
    Images, releases and tags are not workflow runs and are not affected.
  - **Using them:** the Compose project runs a published image when
    `IMAGE_NAMESPACE=ghcr.io/avarcorg` and `BACKEND_VERSION`,
    `FRONTEND_VERSION`, `INGRESS_VERSION` and `KEYCLOAK_VERSION` name a tag (see
    [SPEC-deployment.md](SPEC-deployment.md)). Without a registry
    namespace, a host runs images built on itself (`-Pwith-docker`) under the
    default names and versions. Stage runs the published `snapshot` images;
    prod runs release tags only, once it exists. Deploying a host from the
    published images automatically is not decided yet.

## Open questions

- None at the moment.