# Release Process

This document describes the release workflow for Forge.

## Overview

Releases follow a **notes-first** pattern: release notes land in `main` via PR, then the pipeline validates the build before the release branch is cut.

## Steps

### 1. Create Release Notes

Use the **create-release** custom agent to generate release notes. Select it with the `/agent` command in Copilot CLI, or from the agent menu in VS Code, then ask it to create notes for the version:

```text
Create release notes for {version}
```

This will:
- Analyze commits since the last release tag
- Generate `docs/release-notes/{version}.md` and `docs/release-notes/_announcements/{version}.md`
- Create a `release-notes/{version}` branch and PR into `main`

### 2. Merge to Main

Review the release notes PR and merge it into `main`.

### 3. Run Pipeline

Run the CI/CD pipeline from `main` to validate the build.

### 4. Post Announcement

Post the content from `docs/release-notes/_announcements/{version}.md` to the #forge-releases Teams channel.

### 5. Create Release Branch

Cut the release branch from `main`:

```bash
git checkout main
git pull
git checkout -b releases/{major}.{minor}
git push -u origin releases/{major}.{minor}
```

The pipeline will create the release tag from this branch.

### 6. Bump Version and Re-pin Modules on Main

Run `Set-ForgeVersion.ps1` on `main` to prepare the next release. It updates `MajorVersion` / `MinorVersion` / `PatchVersion` in `.azdo/vars/vars.yml` **and** re-pins the Forge Terraform module constraints (`~> MAJOR.MINOR.0`) in a single step:

```bash
# Increment the minor version (e.g. 3.7.x -> 3.8.0) and re-pin modules
./.github/skills/release-management/scripts/Set-ForgeVersion.ps1 -Bump minor

# Preview first, or target an explicit version
./.github/skills/release-management/scripts/Set-ForgeVersion.ps1 -Bump minor -DryRun
./.github/skills/release-management/scripts/Set-ForgeVersion.ps1 -Version 4.0.0
```

Use `-Bump major` only when preparing a new major release; a `-Bump patch` leaves the Terraform pins unchanged. The script never commits or tags — review the diff, then commit and push directly or via PR.

## Patch Releases

For patches against an existing release:

1. Create a branch off `main` and fix the issue
2. Merge the fix to `main`
3. Backport the fix using the **create-backport** custom agent (select it with `/agent` in Copilot CLI or the agent menu in VS Code), providing the commit and target branch:
   ```text
   Backport commit:{sha} to target:releases/{major}.{minor}
   ```
   This cherry-picks the commit, resolves conflicts, and creates a PR into the release branch.
4. Merge the backport PR into `releases/{major}.{minor}`
5. Use the **create-release** agent for the patch release notes (version `{patch-version}`) and merge to `main`
6. Run the pipeline off the `releases/{major}.{minor}` branch to create the patch tag

## Version Format

Forge uses semantic versioning: `MAJOR.MINOR.PATCH` (e.g., `3.4.0`).

Version is defined in `.azdo/vars/vars.yml` as static values (`MajorVersion`, `MinorVersion`, `PatchVersion`).