Skip to content

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:

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:

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:

# 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: 
    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).