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:
Verify the remote repository name:
git remote -v
Use the correct remote name (usually origin or dahlia) in all push
commands.
Ensure you're on the correct branch and it's up to date.
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
Check out the maintenance branch:
git checkout 1.2-maintenance
git pull
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.
Commit the changes:
git add CHANGES.md
git commit -m "Release 1.2.3"
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
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.
Bump the version in Cargo.toml:
Change version = "1.2.3" to version = "1.2.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.
Check if a newer maintenance branch exists (e.g., 1.3-maintenance):
git branch -a | grep maintenance
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.
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.
Step 1: Prepare the release on main
Check out and update main:
git checkout main
git pull
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.
Commit the changes:
git add CHANGES.md
git commit -m "Release 1.3.0"
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.3.0" 1.3.0
Step 2: Prepare next version on main
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.
Bump the version in Cargo.toml:
Change version = "1.3.0" to version = "1.4.0".
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
Create the maintenance branch from the release tag:
git branch 1.3-maintenance 1.3.0
Check out the maintenance branch:
git checkout 1.3-maintenance
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.
Bump the version in Cargo.toml:
Change version = "1.3.0" to version = "1.3.1".
Commit the version bump:
git add -A
git commit -m "Version bump
[ci skip]"
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:
Hongdown 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}.
- Change description.
- Another change.
For unreleased versions:
Version X.Y.Z
-------------
To be released.
Checklist summary
Patch release checklist
Major/minor release checklist
1---2name: release-33description: >-4 Create and publish releases for the Hongdown project.5 Use when releasing a new version, creating a patch release, or creating6 a major/minor release. Handles CHANGES.md updates, version bumping, tagging,7 and branch management.8metadata:9 source: https://skillmd.com/skills/dahlia/release-310---1112Release skill13=============1415This skill automates the release process for the Hongdown project. There are16two types of releases: patch releases and major/minor releases.171819Prerequisites20-------------2122Before starting any release:23241. Verify the remote repository name:2526 ~~~~ bash27 git remote -v28 ~~~~2930 Use the correct remote name (usually `origin` or `dahlia`) in all push31 commands.32332. Ensure you're on the correct branch and it's up to date.34353. Run tests and quality checks to ensure everything passes:3637 ~~~~ bash38 cargo test && cargo fmt --check && cargo clippy -- -D warnings39 cargo run -- --check *.md40 ~~~~414243Patch releases44--------------4546Patch releases (e.g., 1.2.3) are for bug fixes and small improvements.47They are created from `X.Y-maintenance` branches.4849### Step 1: Prepare the release50511. Check out the maintenance branch:5253 ~~~~ bash54 git checkout 1.2-maintenance55 git pull56 ~~~~57582. Update *CHANGES.md*: Find the section for the version being released and59 change “To be released.” to “Released on {Month} {Day}, {Year}.” using60 the current date in English. For example:6162 ~~~~ markdown63 Version 1.2.364 -------------6566 Released on January 5, 2026.67 ~~~~68693. Commit the changes:7071 ~~~~ bash72 git add CHANGES.md73 git commit -m "Release 1.2.3"74 ~~~~75764. Create the tag (without `v` prefix). Always use `-m` to provide a tag77 message to avoid opening an editor for GPG-signed tags:7879 ~~~~ bash80 git tag -m "Hongdown 1.2.3" 1.2.381 ~~~~8283### Step 2: Prepare next version84851. Add a new section at the top of *CHANGES.md* for the next patch version:8687 ~~~~ markdown88 Version 1.2.489 -------------9091 To be released.929394 Version 1.2.395 -------------9697 Released on January 5, 2026.98 ~~~~991002. Bump the version in *Cargo.toml*:101102 Change `version = "1.2.3"` to `version = "1.2.4"`.1031043. Commit the version bump:105106 ~~~~ bash107 git add -A108 git commit -m "Version bump109110 [ci skip]"111 ~~~~112113### Step 3: Push114115Push the tag and branch to the remote:116117~~~~ bash118git push origin 1.2.3 1.2-maintenance119~~~~120121### Step 4: Cascade merges122123After creating a patch release, you must merge it forward to newer maintenance124branches and eventually to `main`.1251261. Check if a newer maintenance branch exists (e.g., `1.3-maintenance`):127128 ~~~~ bash129 git branch -a | grep maintenance130 ~~~~1311322. If a newer maintenance branch exists, follow these sub-steps:133134 a) Check out the newer branch and merge the tag:135136 ~~~~~137 ~~~~ bash138 git checkout 1.3-maintenance139 git merge 1.2.3140 ~~~~141 ~~~~~142143 b) Resolve any conflicts (commonly in *CHANGES.md* and *Cargo.toml*).144145 c) **Copy changelog entries**: After resolving conflicts, copy the146 changelog entries from the merged tag's version into the current147 branch's unreleased version section. The entries should be inserted148 *above* any existing entries.149150 ~~~~~151 For example, if merging 1.2.3 into 1.3-maintenance where 1.3.2 is152 pending:153154 *Before* (1.3-maintenance):155156 ~~~~ markdown157 Version 1.3.2158 -------------159160 To be released.161162 - Added new logging features.163 ~~~~164165 *Merged tag 1.2.3 contains*:166167 ~~~~ markdown168 Version 1.2.3169 -------------170171 Released on January 6, 2026.172173 - Fixed a crash on startup.174 ~~~~175176 *After* (1.3-maintenance):177178 ~~~~ markdown179 Version 1.3.2180 -------------181182 To be released.183184 - Fixed a crash on startup.185 - Added new logging features.186 ~~~~187 ~~~~~188189 d) Run tests to verify:190191 ~~~~~192 ~~~~ bash193 cargo test && cargo fmt --check && cargo clippy -- -D warnings194 cargo run -- --check *.md195 ~~~~196 ~~~~~197198 e) Complete the merge commit (use default message).199200 f) Create a new patch release for this branch by repeating Steps 1-3201 for version 1.3.x (e.g., 1.3.1).202203 g) Continue cascading to even newer maintenance branches if they exist.2042053. If no newer maintenance branch exists, merge to `main`:206207 ~~~~ bash208 git checkout main209 git merge 1.2.3 # or the last tag you created (e.g., 1.3.1)210 ~~~~211212 Resolve conflicts, run tests, and push:213214 ~~~~ bash215 cargo test && cargo fmt --check && cargo clippy -- -D warnings216 cargo run -- --check *.md217 git push origin main218 ~~~~219220221 > [!IMPORTANT]222 > **Do not add patch release entries into `main`'s unreleased223 > section.** The unreleased section (e.g., `Version 1.3.0`) should224 > only contain entries planned for the next major/minor release. Keep225 > it unchanged.226 >227 > **Do keep all released version sections from the merged tag.**228 > Released version sections (e.g., `Version 1.2.3`) are historical229 > records. They must remain in *CHANGES.md* as their own separate230 > sections placed after the unreleased section — never delete them231 > when resolving conflicts.232 >233 > After conflict resolution, *CHANGES.md* on `main` should look like234 > this (note: `Version 1.3.0` section is unchanged; `Version 1.2.3`235 > section is preserved from the merged tag):236237> ~~~~ markdown238> Version 1.3.0239> -------------240>241> To be released.242>243> - (existing planned entries, untouched)244>245>246> Version 1.2.3247> -------------248>249> Released on January 6, 2026.250>251> - Fixed a crash on startup.252>253>254> Version 1.2.2255> ...256> ~~~~257258259Major/minor releases260--------------------261262Major/minor releases (e.g., 1.3.0, 2.0.0) introduce new features or breaking263changes. They are always created from the `main` branch with patch version 0.264265### Step 1: Prepare the release on main2662671. Check out and update main:268269 ~~~~ bash270 git checkout main271 git pull272 ~~~~2732742. Update *CHANGES.md*: Find the section for the version being released and275 change “To be released.” to “Released on {Month} {Day}, {Year}.” using276 the current date in English. For example:277278 ~~~~ markdown279 Version 1.3.0280 -------------281282 Released on January 5, 2026.283 ~~~~2842853. Commit the changes:286287 ~~~~ bash288 git add CHANGES.md289 git commit -m "Release 1.3.0"290 ~~~~2912924. Create the tag (without `v` prefix). Always use `-m` to provide a tag293 message to avoid opening an editor for GPG-signed tags:294295 ~~~~ bash296 git tag -m "Hongdown 1.3.0" 1.3.0297 ~~~~298299### Step 2: Prepare next version on main3003011. Add a new section at the top of *CHANGES.md* for the next minor version:302303 ~~~~ markdown304 Version 1.4.0305 -------------306307 To be released.308309310 Version 1.3.0311 -------------312313 Released on January 5, 2026.314 ~~~~3153162. Bump the version in *Cargo.toml*:317318 Change `version = "1.3.0"` to `version = "1.4.0"`.3193203. Commit the version bump:321322 ~~~~ bash323 git add -A324 git commit -m "Version bump325326 [ci skip]"327 ~~~~328329### Step 3: Push main and tag330331~~~~ bash332git push origin 1.3.0 main333~~~~334335### Step 4: Create maintenance branch3363371. Create the maintenance branch from the release tag:338339 ~~~~ bash340 git branch 1.3-maintenance 1.3.0341 ~~~~3423432. Check out the maintenance branch:344345 ~~~~ bash346 git checkout 1.3-maintenance347 ~~~~3483493. Add a section for the first patch version in *CHANGES.md*:350351 ~~~~ markdown352 Version 1.3.1353 -------------354355 To be released.356357358 Version 1.3.0359 -------------360361 Released on January 5, 2026.362 ~~~~3633644. Bump the version in *Cargo.toml*:365366 Change `version = "1.3.0"` to `version = "1.3.1"`.3673685. Commit the version bump:369370 ~~~~ bash371 git add -A372 git commit -m "Version bump373374 [ci skip]"375 ~~~~3763776. Push the maintenance branch:378379 ~~~~ bash380 git push origin 1.3-maintenance381 ~~~~382383384Version format reference385------------------------386387 - Patch releases: `X.Y.Z` where Z > 0 (e.g., 1.2.3, 1.2.4)388 - Minor releases: `X.Y.0` (e.g., 1.3.0, 1.4.0)389 - Major releases: `X.0.0` (e.g., 2.0.0, 3.0.0)390 - Maintenance branches: `X.Y-maintenance` (e.g., 1.2-maintenance)391 - Tags: No `v` prefix (e.g., `1.2.3`, not `v1.2.3`)392 - Tag messages: `Hongdown X.Y.Z` format (use `-m` flag to avoid editor)393394395CHANGES.md format396-----------------397398Each version section follows this format:399400~~~~ markdown401Version X.Y.Z402-------------403404Released on {Month} {Day}, {Year}.405406 - Change description.407 - Another change.408~~~~409410For unreleased versions:411412~~~~ markdown413Version X.Y.Z414-------------415416To be released.417~~~~418419420Checklist summary421-----------------422423### Patch release checklist424425 - [ ] Check out `X.Y-maintenance` branch426 - [ ] Update *CHANGES.md* release date427 - [ ] Commit with message “Release X.Y.Z”428 - [ ] Create tag `X.Y.Z` with `-m "Hongdown X.Y.Z"`429 - [ ] Add next version section to *CHANGES.md*430 - [ ] Bump version in *Cargo.toml*431 - [ ] Commit with message `Version bump\n\n[ci skip]`432 - [ ] Push tag and branch433 - [ ] Cascade merge to newer maintenance branches (if any):434 - [ ] Merge tag into newer branch435 - [ ] Copy changelog entries to unreleased version (above existing436 entries)437 - [ ] Run tests and complete merge commit438 - [ ] Create patch release for that branch439 - [ ] Merge to `main` (if no newer maintenance branches):440 - [ ] Resolve *CHANGES.md* conflict: keep `main`'s unreleased section441 unchanged; retain all released version sections from the merged tag442 - [ ] Resolve *Cargo.toml* and *Cargo.lock* conflicts: keep `main`'s443 version444 - [ ] Run tests and push445446### Major/minor release checklist447448 - [ ] Check out `main` branch449 - [ ] Update *CHANGES.md* release date450 - [ ] Commit with message “Release X.Y.0”451 - [ ] Create tag `X.Y.0` with `-m "Hongdown X.Y.0"`452 - [ ] Add next version section to *CHANGES.md*453 - [ ] Bump version in *Cargo.toml*454 - [ ] Commit with message `Version bump\n\n[ci skip]`455 - [ ] Push tag and `main` branch456 - [ ] Create `X.Y-maintenance` branch from tag457 - [ ] Check out maintenance branch458 - [ ] Add patch version section to *CHANGES.md*459 - [ ] Bump version to X.Y.1 in *Cargo.toml*460 - [ ] Commit with message `Version bump\n\n[ci skip]`461 - [ ] Push maintenance branch