Optique Release

Release skill

This skill automates the release process for the Hongdown 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 dahlia) in all push commands.

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

3. Run tests and quality checks to ensure everything passes:

   cargo test && cargo fmt --check && cargo clippy -- -D warnings
   cargo run -- --check *.md

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 "Hongdown 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 Cargo.toml:

   Change version = "1.2.3" to version = "1.2.4".

3. 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, follow these sub-steps:

   a) Check out the newer branch and merge the tag:

   ~~~~ bash
   git checkout 1.3-maintenance
   git merge 1.2.3
   ~~~~

   b) Resolve any conflicts (commonly in CHANGES.md and Cargo.toml).

   c) 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 inserted above any existing entries.

   For example, if merging 1.2.3 into 1.3-maintenance where 1.3.2 is
   pending:
   
   *Before* (1.3-maintenance):
   
   ~~~~ markdown
   Version 1.3.2
   -------------
   
   To be released.
   
    -  Added new logging features.
   ~~~~
   
   *Merged tag 1.2.3 contains*:
   
   ~~~~ markdown
   Version 1.2.3
   -------------
   
   Released on January 6, 2026.
   
    -  Fixed a crash on startup.
   ~~~~
   
   *After* (1.3-maintenance):
   
   ~~~~ markdown
   Version 1.3.2
   -------------
   
   To be released.
   
    -  Fixed a crash on startup.
    -  Added new logging features.
   ~~~~

   d) Run tests to verify:

   ~~~~ bash
   cargo test && cargo fmt --check && cargo clippy -- -D warnings
   cargo run -- --check *.md
   ~~~~

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

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

   g) 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:

   cargo test && cargo fmt --check && cargo clippy -- -D warnings
   cargo run -- --check *.md
   git push origin main

   [!IMPORTANT] Do not add patch release entries into main's unreleased section. The unreleased section (e.g., Version 1.3.0) should only contain entries planned for the next major/minor release. Keep it unchanged.

   Do keep all released version sections from the merged tag. Released version sections (e.g., Version 1.2.3) are historical records. They must remain in CHANGES.md as their own separate sections placed after the unreleased section — never delete them when resolving conflicts.

   After conflict resolution, CHANGES.md on main should look like this (note: Version 1.3.0 section is unchanged; Version 1.2.3 section is preserved from the merged tag):

Version 1.3.0
-------------

To be released.

 -  (existing planned entries, untouched)


Version 1.2.3
-------------

Released on January 6, 2026.

 -  Fixed a crash on startup.


Version 1.2.2
...

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.