# Releasing APL Core

APL Core releases are created with two manually triggered GitHub Actions workflows. Both workflows default to `dry_run: true`; run them in dry-run mode before allowing any writes.

## Release model

A release cycle uses one `releases/v<major.minor>` branch, such as `releases/v1.4`. The branch covers all release candidates, the stable release, and subsequent patch releases in that major/minor series. It is created once and is not recreated.

Git tags are the source of truth for versions. `package.json` remains at `0.0.0`; release workflows derive versions from tags, and builds receive the version through the Dockerfile `VERSION` build argument.

Images built from `main` or feature branches use a development version. The build tag follows the branch name and the VERSION build argument is set to next minor version.

## Version examples

| Event                             | Result          |
| --------------------------------- | --------------- |
| Cut a minor branch after `v6.0.0` | `releases/v6.1` |
| First RC on `releases/v6.1`       | `v6.1.0-rc.1`   |
| Next RC                           | `v6.1.0-rc.2`   |
| Stable promotion                  | `v6.1.0`        |
| First patch RC                    | `v6.1.1-rc.1`   |
| Stable patch promotion            | `v6.1.1`        |
| main or feature branch            | `v6.2.0`        |

## GitHub actions

### Release cut branch

Run the [Release cut branch](.github/workflows/release-cut-branch.yml) workflow from the branch that should start the release cycle, normally `main`.
The workflow finds the highest stable tag in the repository, applies the requested version bump, runs the release checks, and creates the new release branch. It does not create a release tag or publish artifacts.

1. Open **Actions > Release cut branch > Run workflow**.
2. Choose a `bump_type` of `minor` or `major`.
3. Set `base_branch`, normally `main`.
4. Keep `release_branch_prefix` set to `releases/`.
5. Run once with `dry_run` enabled.
6. Review the run, then run again with `dry_run` disabled.

Equivalent GitHub CLI commands for a minor release cycle from `main`:

```bash
# Dry run
gh workflow run release-cut-branch.yml --ref main \
	-f bump_type=minor \
	-f dry_run=true

# Create the branch after reviewing the dry run
gh workflow run release-cut-branch.yml --ref main \
	-f bump_type=minor \
	-f dry_run=false
```

### Release create from branch

Run the [Release create from branch](.github/workflows/release-create-from-branch.yml) workflow from an existing `releases/*` branch.

For a release candidate, the workflow increments the highest RC tag on the branch. If the branch has no tags, it derives the initial version from the branch name and starts at `rc.1`. For a stable release, it removes the RC suffix from the highest release candidate tag.

The workflow validates dependencies and publishes the Git tag, GitHub release, container image, and Helm chart. The same release branch is used for later patch release candidates and stable patch releases.

GitHub CLI commands for an RC on `releases/v6.1`:

```bash
# Publish the RC after reviewing the dry run
gh workflow run release-create-from-branch.yml --ref releases/v6.1 \
	-f is_prerelease=true \
	-f dry_run=false
```

To promote the current RC to stable, use the same release branch with `is_prerelease=false`:

```bash
# Publish the stable release after reviewing the dry run
gh workflow run release-create-from-branch.yml --ref releases/v6.1 \
	-f is_prerelease=false \
	-f dry_run=false
```

The same action can be performed in the GitHub web interface by navigating to **Actions > Release create from branch > Run workflow**.

# Release notes

The `What has changed` section is generated automatically during the release process.
There are three manual steps that need to be performed to enrich the release notes:

1. Add summary
2. Render the updated app table `cd ci && npm run render-chart-version-changes -- <old-tag> <new-tag>` and copy the output to the corresponding GitHub release notes.
3. Add the `# Internal component release notes` section containing links to apl-api, apl-console, and apl-tasks release notes (if applicable).