release

name	release
description	Create and publish releases for the Optique project. Use when releasing a new version, creating a patch release, or creating a major/minor release. Handles CHANGES.md updates, version bumping, tagging, and branch management.
metadata	{"internal":true}

Release skill

This skill automates the release process for the Optique project. There are two types of releases: patch releases and major/minor releases.

Prerequisites

Before starting any release:

1. Verify the remote repository name:

   git remote -v
   

   Use the correct remote name (usually origin or upstream) in all push commands.

2. Ensure you're on the correct branch and it's up to date.

3. Run tests to ensure everything passes:

   mise test
   mise check
   

Patch releases

Patch releases (e.g., 1.2.3) are for bug fixes and small improvements. They are created from X.Y-maintenance branches.

Step 1: prepare the release

1. Check out the maintenance branch:

   git checkout 1.2-maintenance
   git pull
   

2. Update CHANGES.md: Find the section for the version being released and change “To be released.” to “Released on {Month} {Day}, {Year}.” using the current date in English. For example:

   Version 1.2.3
   -------------
   
   Released on January 5, 2026.
   

3. Commit the changes:

   git add CHANGES.md
   git commit -m "Release 1.2.3"
   

4. Create the tag (without v prefix). Always use -m to provide a tag message to avoid opening an editor for GPG-signed tags:

   git tag -m "Optique 1.2.3" 1.2.3
   

Step 2: prepare next version

1. Add a new section at the top of CHANGES.md for the next patch version:

   Version 1.2.4
   -------------
   
   To be released.
   
   
   Version 1.2.3
   -------------
   
   Released on January 5, 2026.
   

2. Bump the version in packages/core/deno.json:

   Change "version": "1.2.3" to "version": "1.2.4".

3. Run the version sync script:

   mise check-versions --fix
   

4. Commit the version bump:

   git add -A
   git commit -m "Version bump
   
   [ci skip]"
   

Step 3: push

Push the tag and branch to the remote:

git push origin 1.2.3 1.2-maintenance

Step 4: cascade merges

After creating a patch release, you must merge it forward to newer maintenance branches and eventually to main.

1. Check if a newer maintenance branch exists (e.g., 1.3-maintenance):

   git branch -a | grep maintenance
   

2. If a newer maintenance branch exists:

   1. Check out the newer branch and merge the tag:

      git checkout 1.3-maintenance
      git merge 1.2.3
      

   2. Resolve any conflicts (commonly in CHANGES.md, deno.json, and package.json files).

   3. Copy changelog entries: After resolving conflicts, copy the changelog entries from the merged tag's version into the current branch's unreleased version section. The entries should be:

      • Grouped by package (e.g., ### @optique/core, ### @optique/run)
      • Inserted above any existing entries in each package section
      • Issue/PR reference definitions (e.g., [#123]: ...) should not be duplicated if they already exist

      For example, if merging 1.2.3 into 1.3-maintenance where 1.3.2 is pending:

      Before (1.3-maintenance):

      Version 1.3.2
      -------------
      
      To be released.
      
      ### @optique/run
      
       -  Added new logging features.  [[#125]]
      
      [#125]: https://github.com/dahlia/optique/issues/125
      

      Merged tag 1.2.3 contains:

      Version 1.2.3
      -------------
      
      Released on January 6, 2026.
      
      ### @optique/run
      
       -  Fixed a crash on startup.  [[#123]]
      
      [#123]: https://github.com/dahlia/optique/issues/123
      

      After (1.3-maintenance):

      Version 1.3.2
      -------------
      
      To be released.
      
      ### @optique/run
      
       -  Fixed a crash on startup.  [[#123]]
       -  Added new logging features.  [[#125]]
      
      [#123]: https://github.com/dahlia/optique/issues/123
      [#125]: https://github.com/dahlia/optique/issues/125
      

   4. Run tests to verify:

      mise test
      mise check
      

   5. Complete the merge commit (use default message).

   6. Create a new patch release for this branch by repeating Steps 1-3 for version 1.3.x (e.g., 1.3.1).

   7. Continue cascading to even newer maintenance branches if they exist.

3. If no newer maintenance branch exists, merge to main:

   git checkout main
   git merge 1.2.3  # or the last tag you created (e.g., 1.3.1)
   

   Resolve conflicts, run tests, and push:

   mise test
   mise check
   git push origin main
   

   [!IMPORTANT] Do not copy changelog entries to main. The main branch tracks the next major/minor release, so patch release entries should not be duplicated there. Just resolve conflicts and keep the existing unreleased section as-is.

Major/minor releases

Major/minor releases (e.g., 1.3.0, 2.0.0) introduce new features or breaking changes. They are always created from the main branch with patch version 0.

Step 1: prepare the release on main

1. Check out and update main:

   git checkout main
   git pull
   

2. Update CHANGES.md: Find the section for the version being released and change “To be released.” to “Released on {Month} {Day}, {Year}.” using the current date in English. For example:

   Version 1.3.0
   -------------
   
   Released on January 5, 2026.
   

3. Commit the changes:

   git add CHANGES.md
   git commit -m "Release 1.3.0"
   

4. Create the tag (without v prefix). Always use -m to provide a tag message to avoid opening an editor for GPG-signed tags:

   git tag -m "Optique 1.3.0" 1.3.0
   

Step 2: prepare next version on main

1. Add a new section at the top of CHANGES.md for the next minor version:

   Version 1.4.0
   -------------
   
   To be released.
   
   
   Version 1.3.0
   -------------
   
   Released on January 5, 2026.
   

2. Bump the version in packages/core/deno.json:

   Change "version": "1.3.0" to "version": "1.4.0".

3. Run the version sync script:

   mise check-versions --fix
   

4. Commit the version bump:

   git add -A
   git commit -m "Version bump
   
   [ci skip]"
   

Step 3: push main and tag

git push origin 1.3.0 main

Step 4: create maintenance branch

1. Create the maintenance branch from the release tag:

   git branch 1.3-maintenance 1.3.0
   

2. Check out the maintenance branch:

   git checkout 1.3-maintenance
   

3. Add a section for the first patch version in CHANGES.md:

   Version 1.3.1
   -------------
   
   To be released.
   
   
   Version 1.3.0
   -------------
   
   Released on January 5, 2026.
   

4. Bump the version in packages/core/deno.json:

   Change "version": "1.3.0" to "version": "1.3.1".

5. Run the version sync script:

   mise check-versions --fix
   

6. Commit the version bump:

   git add -A
   git commit -m "Version bump
   
   [ci skip]"
   

7. Push the maintenance branch:

   git push origin 1.3-maintenance
   

Version format reference

• Patch releases: X.Y.Z where Z > 0 (e.g., 1.2.3, 1.2.4)
• Minor releases: X.Y.0 (e.g., 1.3.0, 1.4.0)
• Major releases: X.0.0 (e.g., 2.0.0, 3.0.0)
• Maintenance branches: X.Y-maintenance (e.g., 1.2-maintenance)
• Tags: No v prefix (e.g., 1.2.3, not v1.2.3)
• Tag messages: Optique X.Y.Z format (use -m flag to avoid editor)

CHANGES.md format

Each version section follows this format:

Version X.Y.Z
-------------

Released on {Month} {Day}, {Year}.

### @optique/core

 -  Change description.  [[#123]]

### @optique/run

 -  Change description.

[#123]: https://github.com/dahlia/optique/issues/123

For unreleased versions:

Version X.Y.Z
-------------

To be released.

Checklist summary

Patch release checklist

• Check out X.Y-maintenance branch
• Update CHANGES.md release date
• Commit with message “Release X.Y.Z”
• Create tag X.Y.Z with -m "Optique X.Y.Z"
• Add next version section to CHANGES.md
• Bump version in packages/core/deno.json
• Run mise check-versions --fix
• Commit with message Version bump\n\n[ci skip]
• Push tag and branch
• Cascade merge to newer maintenance branches (if any):
  • Merge tag into newer branch
  • Copy changelog entries to unreleased version (above existing entries)
  • Run tests and complete merge commit
  • Create patch release for that branch
• Merge to main (if no newer maintenance branches)

Major/minor release checklist

• Check out main branch
• Update CHANGES.md release date
• Commit with message “Release X.Y.0”
• Create tag X.Y.0 with -m "Optique X.Y.0"
• Add next version section to CHANGES.md
• Bump version in packages/core/deno.json
• Run mise check-versions --fix
• Commit with message Version bump\n\n[ci skip]
• Push tag and main branch
• Create X.Y-maintenance branch from tag
• Check out maintenance branch
• Add patch version section to CHANGES.md
• Bump version to X.Y.1 in packages/core/deno.json
• Run mise check-versions --fix
• Commit with message Version bump\n\n[ci skip]
• Push maintenance branch