Agent skill for release automation

.github/skills/prepare-release/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: prepare-release
+description: "Prepare a release for the Feature Management .NET SDK. Use when user mentions release preparation, version bump, creating merge PRs, preview release, or stable release for this project."
+---
+
+# Prepare Release
+
+This skill automates the release preparation workflow for the [Feature Management .NET SDK](https://github.com/microsoft/FeatureManagement-Dotnet) project.
+
+## When to Use This Skill
+
+Use this skill when you need to:
+- Bump the package version for a new stable or preview release
+- Create merge PRs to sync branches (main → release, preview → release)
+- Prepare all the PRs needed before publishing a new release
+
+## Background
+
+### Repository Information
+- **GitHub Repo**: https://github.com/microsoft/FeatureManagement-Dotnet
+- **Packages** (all 3 are released together with the same version):
+  1. `Microsoft.FeatureManagement` — Base package
+  2. `Microsoft.FeatureManagement.AspNetCore` — ASP.NET Core package
+  3. `Microsoft.FeatureManagement.Telemetry.ApplicationInsights` — Application Insights telemetry package
+
+### Branch Structure
+- `main` – primary development branch for stable releases
+- `preview` – development branch for preview releases
+- `release/v{major}` – release branch (e.g., `release/v4`)
+
+### Version Files
+The version is defined by `<MajorVersion>`, `<MinorVersion>`, `<PatchVersion>`, and optionally `<PreviewVersion>` properties in **all three** `.csproj` files simultaneously:
+1. `src/Microsoft.FeatureManagement/Microsoft.FeatureManagement.csproj`
+2. `src/Microsoft.FeatureManagement.AspNetCore/Microsoft.FeatureManagement.AspNetCore.csproj`
+3. `src/Microsoft.FeatureManagement.Telemetry.ApplicationInsights/Microsoft.FeatureManagement.Telemetry.ApplicationInsights.csproj`
+
+Each file contains a version block like:
+```xml
+<!-- Official Version -->
+<PropertyGroup>
+  <MajorVersion>4</MajorVersion>
+  <MinorVersion>1</MinorVersion>
+  <PatchVersion>0</PatchVersion>
+</PropertyGroup>
+```
+
+For preview versions, a `<PreviewVersion>` line is also present:
+```xml
+<!-- Official Version -->
+<PropertyGroup>
+  <MajorVersion>4</MajorVersion>
+  <MinorVersion>0</MinorVersion>
+  <PatchVersion>0</PatchVersion>
+  <PreviewVersion>-preview5</PreviewVersion>
+</PropertyGroup>
+```
+
+### Version Format
+- **Stable**: `{major}.{minor}.{patch}` (e.g., `4.1.0`)
+- **Preview**: `{major}.{minor}.{patch}-preview{N}` (e.g., `4.0.0-preview5`)
+
+## Quick Start
+
+Ask the user whether this is a **stable** or **preview** release, and what the **new version number** should be. Then follow the appropriate workflow below.
+
+---
+
+### Workflow A: Stable Release
+
+#### Step 1: Version Bump PR
+
+Create a version bump PR targeting `main` by running the version bump script:
+
+```powershell
+.\scripts\version-bump.ps1 <new_version>
+```
+
+For example: `.\scripts\version-bump.ps1 4.2.0`
+
+The script will automatically:
+1. Read the current version from the first `.csproj` file.
+2. Create a new branch from `main` named `<username>/version-bump-<new_version>` (e.g., `linglingye/version-bump-4.2.0`).
+3. Update `<MajorVersion>`, `<MinorVersion>`, `<PatchVersion>` in all three `.csproj` files, and remove `<PreviewVersion>` if present.
+4. Commit, push, and create a PR to `main` with title: `Version bump <new_version>`.
+
+When the script prompts `Proceed? [y/N]`, confirm by entering `y`.
+
+**Sample PR**: https://github.com/microsoft/FeatureManagement-Dotnet/pull/540
+
+#### Step 2: Merge Main to Release Branch
+
+After the version bump PR is merged, create a PR to merge `main` into the release branch by running:
+
+```powershell
+.\scripts\merge-to-release.ps1 <new_version>
+```
+
+For example: `.\scripts\merge-to-release.ps1 4.2.0`
+
+When the script prompts `Proceed? [y/N]`, confirm by entering `y`.
+
+> **Important**: Use "Create a merge commit" (not "Squash and merge") when merging this PR to preserve commit history.
+
+**Sample PR**: https://github.com/microsoft/FeatureManagement-Dotnet/pull/541
+
+---
+
+### Workflow B: Preview Release
+
+#### Step 1: Version Bump PR
+
+Create a version bump PR targeting `preview` by running the version bump script with the `-Preview` flag:
+
+```powershell
+.\scripts\version-bump.ps1 <new_version> -Preview
+```
+
+For example: `.\scripts\version-bump.ps1 4.0.0-preview4 -Preview`
+
+When the script prompts `Proceed? [y/N]`, confirm by entering `y`.
+
+**Sample PR**: https://github.com/microsoft/FeatureManagement-Dotnet/pull/476
+
+#### Step 2: Merge Preview to Release Branch
+
+After the version bump PR is merged, create a PR to merge `preview` into the release branch by running:
+
+```powershell
+.\scripts\merge-to-release.ps1 <new_version> -Preview
+```
+
+For example: `.\scripts\merge-to-release.ps1 4.0.0-preview4 -Preview`
+
+When the script prompts `Proceed? [y/N]`, confirm by entering `y`.
+
+> **Important**: Use "Create a merge commit" (not "Squash and merge") when merging this PR to preserve commit history.
+
+**Sample PR**: https://github.com/microsoft/FeatureManagement-Dotnet/pull/477
+
+---
+
+## Review Checklist
+
+Each PR should be reviewed with the following checks:
+- [ ] Version is updated consistently across all 3 `.csproj` files
+- [ ] No unintended file changes are included
+- [ ] Merge PRs use **merge commit** strategy (not squash)
+- [ ] Branch names follow the naming conventions
+- [ ] All CI checks pass

scripts/merge-to-release.ps1

@@ -0,0 +1,100 @@
+<#
+.SYNOPSIS
+    Creates a PR to merge a development branch into its corresponding release branch.
+.DESCRIPTION
+    Used after a version bump PR has been merged. Creates a PR from main (or preview)
+    into the appropriate release branch via the GitHub CLI (gh).
+.PARAMETER Version
+    The version that was just bumped (used to determine major version and PR title)
+.PARAMETER Preview
+    Merge preview -> release/v{major} instead of main -> release/v{major}
+.EXAMPLE
+    .\scripts\merge-to-release.ps1 4.2.0
+    # main -> release/v4
+.EXAMPLE
+    .\scripts\merge-to-release.ps1 4.0.0-preview5 -Preview
+    # preview -> release/v4
+.NOTES
+    Prerequisites: git and gh (GitHub CLI) must be installed and authenticated
+#>
+
+param(
+    [Parameter(Mandatory = $true, Position = 0)]
+    [string]$Version,
+
+    [switch]$Preview
+)
+
+$ErrorActionPreference = "Stop"
+
+# ── Validate version format ──────────────────────────────────────────────────
+
+if ($Version -notmatch '^\d+\.\d+\.\d+(-preview\d+)?$') {
+    Write-Error "Invalid version format '$Version'. Expected: X.Y.Z or X.Y.Z-previewN"
+    exit 1
+}
+
+# ── Determine branches ───────────────────────────────────────────────────────
+
+# Extract major version (e.g. "4" from "4.2.0" or "4.0.0-preview5")
+$MajorVersion = ($Version -split '\.')[0]
+
+if ($Preview) {
+    $SourceBranch = "preview"
+    $TargetBranch = "release/v$MajorVersion"
+    $PrTitle = "Merge preview to release/v$MajorVersion"
+}
+else {
+    $SourceBranch = "main"
+    $TargetBranch = "release/v$MajorVersion"
+    $PrTitle = "Merge main to release/v$MajorVersion"
+}
+
+Write-Host "-- Source branch : $SourceBranch"
+Write-Host "-- Target branch : $TargetBranch"
+Write-Host "-- PR title      : $PrTitle"
+Write-Host ""
+
+# ── Confirm with user ────────────────────────────────────────────────────────
+
+$confirm = Read-Host "Proceed? [y/N]"
+if ($confirm -notmatch '^[Yy]$') {
+    Write-Host "Aborted."
+    exit 0
+}
+Write-Host ""
+
+# ── Resolve project directory ────────────────────────────────────────────────
+
+$ProjectDir = Split-Path $PSScriptRoot -Parent
+Push-Location $ProjectDir
+
+try {
+    # ── Fetch latest branches ────────────────────────────────────────────────
+
+    Write-Host "-- Fetching latest branches..."
+    git fetch origin $SourceBranch
+    git fetch origin $TargetBranch
+
+    # ── Create PR ────────────────────────────────────────────────────────────
+
+    Write-Host "-- Creating pull request..."
+    $Body = @"
+Merge ``$SourceBranch`` into ``$TargetBranch`` after version bump ``$Version``.
+
+> **Important**: Use **Create a merge commit** (not "Squash and merge") when merging this PR to preserve commit history.
+
+---
+*This PR was created automatically by ``scripts/merge-to-release.ps1``.*
+"@
+
+    $PrUrl = gh pr create --base $TargetBranch --head $SourceBranch --title $PrTitle --body $Body
+
+    Write-Host ""
+    Write-Host "-- Done! PR created: $PrUrl"
+    Write-Host ""
+    Write-Host "WARNING: Use 'Create a merge commit' (not 'Squash and merge') when merging this PR."
+}
+finally {
+    Pop-Location
+}