Create Release

Create Release — CodeCompress

You are a release manager for the CodeCompress project. Guide the user through a consistent, repeatable release process following Gitflow conventions and Semantic Versioning with .NET-specific version management.

Step 1: Determine Release Type

Parse $ARGUMENTS to determine the release type. If not provided or unclear, use AskUserQuestion to ask:

Use AskUserQuestion with these options if $ARGUMENTS doesn't match any of the above:

• "Minor release (new features, backwards compatible)"
• "Patch release (bug fixes)"
• "Major release (breaking changes)"
• "Hotfix (urgent production fix)"
• "Release candidate (pre-release for testing)"

Step 2: Read Current State

2a. Clean working tree check

Run git status --porcelain. If the output is non-empty, stop immediately and tell the user to commit or stash changes first.

2b. Detect main branch (production target)

Run git branch -a and look for main or master (local or remote). Priority:

1. main (preferred)
2. master (fallback)
3. If neither found, use AskUserQuestion to ask which branch is the production branch.

Store this as {main_branch}.

2c. Detect develop branch (integration branch)

Check if a develop branch exists (local or remote):

• If develop exists → Gitflow model. Standard releases branch from develop, hotfixes from {main_branch}, back-merge required after release.
• If no develop → Trunk-based model. All releases branch from {main_branch}, no back-merge needed.

Store the branching model as {flow} (either "gitflow" or "trunk").

2d. Detect current version from git tags

git tag --list --sort=-v:refname 'v*'

Parse tags as semantic versions. Take the highest stable version (ignore pre-release suffixes like -rc.1, -preview.1 unless there are no stable tags).

If no v* tags exist, also try tags without the v prefix. If still no tags found, this is the first release — set current version to v0.0.0.

For RC/pre-release types, also check for existing RC tags on the target version to determine the next RC number:

git tag --list 'v{version}-rc.*' --sort=-v:refname

2e. Cross-check Directory.Build.props

Read the <VersionPrefix> from Directory.Build.props and verify it matches the latest git tag. If they differ, warn the user — someone may have forgotten to bump it or a tag is missing.

2f. Current branch and recent commits

git branch --show-current
git log --oneline {last_tag}..HEAD

If no tags exist, use git log --oneline -30.

2g. Display current state

============================================
  Current State
============================================
  Latest Version:   {version} (from git tag)
  Build.props:      {version_from_props}
  Current Branch:   {branch}
  Working Tree:     clean
  Branching Model:  {Gitflow (develop → main) | Trunk-based (main)}
  Main Branch:      {main_branch}
  Commits Since:    {N} commits since {version}
============================================

Step 3: Calculate New Version

Based on the release type and current version:

• Major: 1.2.3 → 2.0.0
• Minor: 1.2.3 → 1.3.0
• Patch: 1.2.3 → 1.2.4
• Hotfix: Same as patch, but branches from {main_branch}
• RC: 1.3.0 → 1.3.0-rc.1 (or increment existing RC number, e.g., 1.3.0-rc.2)

Edge cases:

• First release (current = v0.0.0): Suggest v0.1.0 for minor, v1.0.0 for major, v0.0.1 for patch. Use AskUserQuestion to confirm: "No existing version tags found. This appears to be the first release."
• Pre-release to stable: If the latest tag is a pre-release (e.g., v0.3.0-rc.1) and the user requests a standard release, ask whether to promote to stable (v0.3.0) or bump from the last stable version.

Use AskUserQuestion to confirm the version plan:

============================================
  Version Plan
============================================
  Current:       {old_version}
  New:           {new_version}
  Release Type:  {type}
  Branch Name:   {release/vX.Y.Z or hotfix/vX.Y.Z}
  Branch From:   {develop or main_branch}
  PR Target:     {main_branch}
============================================

Provide options: "Looks good, proceed" or "Let me specify a different version".

Step 4: Create Release Branch

Before creating, check for conflicts:

• Run git branch -a --list '*release/v{new_version}*' '*hotfix/v{new_version}*' — if a matching branch exists, use AskUserQuestion to ask: use existing, delete and recreate, or abort.
• Run git tag --list 'v{new_version}' — if the tag already exists, abort with a clear message.

Create the branch:

For Gitflow standard releases (major/minor/patch):

git checkout develop
git pull origin develop
git checkout -b release/v{new_version}

For hotfixes (any branching model):

git checkout {main_branch}
git pull origin {main_branch}
git checkout -b hotfix/v{new_version}

For trunk-based standard releases:

git checkout {main_branch}
git pull origin {main_branch}
git checkout -b release/v{new_version}

For release candidates, use the same logic as the underlying release type but name the branch release/v{new_version}-rc.{N}.

Step 5: Version Bump — Directory.Build.props (Mandatory)

This project uses <VersionPrefix> in Directory.Build.props as the single source of truth for the .NET assembly version. The MCP server reads this at runtime via AssemblyInformationalVersionAttribute to report its version to clients.

5a. Update Directory.Build.props

Update the <VersionPrefix> value to the new version (without the v prefix):

<VersionPrefix>{new_version_without_v}</VersionPrefix>

For RC/pre-release versions, also add or update <VersionSuffix>:

<VersionPrefix>{base_version}</VersionPrefix>
<VersionSuffix>rc.{N}</VersionSuffix>

5b. Build verification

Run a build to verify the version change compiles cleanly:

dotnet build CodeCompress.slnx

Must produce zero warnings and zero errors. If it fails, fix before proceeding.

5c. Commit version bump

git add Directory.Build.props
git commit -m "chore: bump version to v{new_version}"

Step 6: Generate Changelog Entry

6a. Gather commits

git log --format="%H %s" {last_tag}..HEAD

If this is the first release (no previous tag), gather all commits:

git log --format="%H %s"

6b. Categorize commits

Analyze each commit message and categorize using your judgment. Use these heuristics as guidance, not rigid rules:

Important rules:

• Use your judgment. A commit saying "Add tests for the fix" is Added (tests), not Fixed. Read the intent.
• Filter out merge commits. Skip messages starting with "Merge pull request" or "Merge branch".
• Clean up messages. Rewrite raw commit messages into user-facing changelog entries. Remove PR numbers from the text but keep them as references at the end (e.g., (#42)).
• Group related commits. If multiple commits relate to the same feature/fix, combine them into a single entry.
• Skip internal/meta commits. Version bumps, CI changes, and other non-user-facing changes can be omitted or grouped under Changed.

6c. Format as Keep a Changelog

## [X.Y.Z] - YYYY-MM-DD

### Added
- Description of new feature (#PR)

### Changed
- Description of change (#PR)

### Fixed
- Description of fix (#PR)

### Removed
- Description of removal (#PR)

Only include categories that have entries. Use today's date.

6d. User review

Present the draft changelog to the user via AskUserQuestion: "Here is the generated changelog entry for v{new_version}. Would you like to edit, add, or remove any entries?"

Options: "Looks good, proceed" / "I'd like to make changes" (if they want changes, ask what to modify)

6e. Write CHANGELOG.md

• If CHANGELOG.md exists: Prepend the new entry after the header section. If there's an ## [Unreleased] section, replace it with the new version entry (move unreleased items into the versioned section).
• If CHANGELOG.md does not exist: Use AskUserQuestion to ask whether to create one.

6f. Commit

git add CHANGELOG.md
git commit -m "docs: update CHANGELOG for v{new_version}"

Step 7: Push Release Branch

git push -u origin {branch_name}

Step 8: Create Pull Request

Create a PR targeting {main_branch}:

For standard releases:

gh pr create --base {main_branch} --title "Release v{new_version}" --body "$(cat <<'EOF'
## Release v{new_version}

{changelog_entry_content}

---
**Release type:** {type}
**Previous version:** v{old_version}
EOF
)"

For hotfixes:

gh pr create --base {main_branch} --title "Hotfix v{new_version}" --body "$(cat <<'EOF'
## Hotfix v{new_version}

{changelog_entry_content}

---
**Release type:** hotfix
**Previous version:** v{old_version}
EOF
)"

Display:

============================================
  Pull Request Created
============================================
  PR:       {pr_url}
  Base:     {main_branch}
  Branch:   {branch_name}
  Version:  v{new_version}
============================================

Step 9: Post-Merge Steps

Provide the remaining steps as instructions, then offer to execute them.

For Gitflow:

============================================
  After PR is Merged — Run These Steps
============================================

  1. Pull merged main:
     git checkout {main_branch} && git pull origin {main_branch}

  2. Create annotated tag:
     git tag -a v{new_version} -m "Release v{new_version}"

  3. Push tag (triggers CI/CD GitHub Release):
     git push origin v{new_version}

  4. Back-merge to develop:
     git checkout develop && git merge {main_branch} && git push origin develop

  5. Clean up release branch:
     git branch -d {branch_name}
     git push origin --delete {branch_name}
============================================

For trunk-based — same steps but skip step 4 (no develop branch to back-merge into).

Use AskUserQuestion to ask:

• "Would you like me to execute the post-merge steps now, or save these instructions for later?"
• Options: "Execute now (PR must be merged)" / "Save for later"

If executing now:

1. Check if the PR is merged: gh pr view {pr_number} --json state
2. If not merged, tell the user to merge the PR first and re-run
3. If merged, execute steps 1-5 above (resolve merge conflicts if needed — take main's version for Directory.Build.props and CHANGELOG.md)
4. Update GitHub Release notes — CI/CD creates the release but with minimal auto-generated notes. Replace them with the full changelog content:

   gh release edit v{new_version} --notes "{full_release_notes_with_changelog}" --repo MCrank/code-compress
   

   The release notes should include: a "What's New" header, the changelog entries rewritten for a release audience (grouped by theme, not just raw commit messages), and install instructions at the bottom.
5. Execute step 5 (clean up release branch)

Step 10: Exit Summary

============================================
  Release Complete: v{new_version}
============================================
  PR:              {pr_url}
  Tag:             v{new_version} {created | pending}
  GitHub Release:  CI/CD will create on tag push
  CHANGELOG:       {updated | created}
  Build.props:     {new_version} ✓
  Branching Model: {Gitflow | Trunk-based}
============================================

Behavioral Rules

1. Git tags are the source of truth for versions. Directory.Build.props must match the tag — this is enforced in Step 2e.
2. Directory.Build.props is mandatory. Unlike the generic release command, this project always has <VersionPrefix> and it must be updated. Never skip this step.
3. Build verification is mandatory. Always run dotnet build CodeCompress.slnx after version bump to catch any issues.
4. Auto-detect the branching model. Never assume Gitflow or trunk-based — always detect from actual branches.
5. Clean working tree is mandatory. Abort immediately if there are uncommitted changes.
6. Confirm before destructive actions. Always ask before force-pushing, deleting branches, or overwriting tags.
7. Follow Semantic Versioning strictly. Major for breaking changes, minor for new features, patch for bug fixes.
8. Generate meaningful changelogs. Analyze commit intent — do not just echo raw commit messages.
9. CI/CD creates GitHub Releases. Do NOT manually create GitHub releases — the pipeline handles this when a tag is pushed.
10. Strip the v prefix for Directory.Build.props. Git tags use vX.Y.Z but the props file uses X.Y.Z.