# Release process

Arcade ships to self-hosted customers as one Helm chart, `arcade`, versioned
`X.Y.Z`. Each chart version pins every Arcade image to a single app version, the
source revision those images were built from, shown as **App version** on each
release.

## Release cadence

Arcade is moving to a regular release train:

| Release     | Cadence | What it carries                                                 |
| ----------- | ------- | --------------------------------------------------------------- |
| Pre-release | Weekly  | Everything merged since the last release, for early evaluation. |
| Supported   | Monthly | The release we recommend running in production.                 |
| Patch       | Weekly  | Non-breaking fixes against the current supported release.       |

A supported release is cut on the first Tuesday of every month. It receives
patches until the next supported release ships. Talk to your Arcade contact if
you need a longer support window.

## What every release includes

- **Release notes** that open with the new features worth upgrading for, then
  **Upgrade notes** listing anything you must do before or during the upgrade,
  and operator notes on security, fixes and configuration changes.
- **The Helm chart**, published to the public OCI registry
  `oci://public.ecr.aws/s5i6x9d1/charts/arcade` and listed on
  [Artifact Hub](https://artifacthub.io/packages/helm/arcade/arcade), which
  documents every chart value.
- **The services** the chart deploys with its default values, with any service
  new in that release flagged.
- **Image digests** for every container the chart deploys. Arcade images are
  multi-architecture (`linux/amd64` and `linux/arm64`) and published to both
  Docker Hub (`arcadedev/*`) and Quay (`quay.io/arcade/*`).
- **SBOMs**: one SPDX 2.3 and one CycloneDX document per image, generated with
  syft from the published images.
- **A vulnerability scan** of those SBOMs with grype. Scans are refreshed
  nightly, so a release's counts change as new advisories are published.
- **Database migrations**: the exact SQL each upgrade applies, per service, and
  a warning when a release introduces a new database.
- **The event registry**: every product analytics event the release emits, with
  each property's on-premises disposition, and the fields of audit log records.

## Preview releases

Each night an automated job forecasts the next release from the current main
branch. It drafts the release notes, renders the migrations and event registry
changes, and inventories and scans the candidate images. The forecast is
published under **Preview**. Contents, notes and the
version number can change before the release is cut.

## Upgrading

- Read the upgrade notes of **every** release between your current version and
  the target. Upgrade notes are not repeated in later releases.
- Back up each database before upgrading. Downgrading the chart does not reverse
  a migration.
- Migrations run automatically on `helm upgrade`. Engine and coordinator
  migrations run as pre-upgrade hooks, so a failing migration aborts the
  upgrade before new pods roll out. Experience API migrations run in an init
  container, so a failure leaves that pod waiting in `Init`.
- If you set `<service>.database.migrations: false`, apply that service's
  `.apply.sql` from the release's **Migrations** section before rolling out the
  new images.
- A release that adds a database is flagged. The chart creates it on the shared
  Postgres unless you point the service at your own database, so provision or
  approve it before upgrading.

## Verifying what you deploy

Pin images by digest. Each release lists the digest every image tag resolved to
when it was released, and the SBOM bundle's `index.json` ties each document to
both that digest and the `linux/amd64` manifest it describes.