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: ~~~~ bash 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: ~~~~ bash 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: ~~~~ bash 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: ~~~~ markdown Version 1.2.3 ------------- Released on January 5, 2026. ~~~~ 3. Commit the changes: ~~~~ bash 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: ~~~~ bash 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: ~~~~ markdown 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: ~~~~ bash git add -A git commit -m "Version bump [ci skip]" ~~~~ ### Step 3: Push Push the tag and branch to the remote: ~~~~ bash 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`): ~~~~ bash 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`: ~~~~ bash 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: ~~~~ bash 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): > ~~~~ markdown > 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 1. Check out and update main: ~~~~ bash 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: ~~~~ markdown Version 1.3.0 ------------- Released on January 5, 2026. ~~~~ 3. Commit the changes: ~~~~ bash 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: ~~~~ bash git tag -m "Hongdown 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: ~~~~ markdown Version 1.4.0 ------------- To be released. Version 1.3.0 ------------- Released on January 5, 2026. ~~~~ 2. Bump the version in *Cargo.toml*: Change `version = "1.3.0"` to `version = "1.4.0"`. 3. Commit the version bump: ~~~~ bash git add -A git commit -m "Version bump [ci skip]" ~~~~ ### Step 3: Push main and tag ~~~~ bash git push origin 1.3.0 main ~~~~ ### Step 4: Create maintenance branch 1. Create the maintenance branch from the release tag: ~~~~ bash git branch 1.3-maintenance 1.3.0 ~~~~ 2. Check out the maintenance branch: ~~~~ bash git checkout 1.3-maintenance ~~~~ 3. Add a section for the first patch version in *CHANGES.md*: ~~~~ markdown Version 1.3.1 ------------- To be released. Version 1.3.0 ------------- Released on January 5, 2026. ~~~~ 4. Bump the version in *Cargo.toml*: Change `version = "1.3.0"` to `version = "1.3.1"`. 5. Commit the version bump: ~~~~ bash git add -A git commit -m "Version bump [ci skip]" ~~~~ 6. Push the maintenance branch: ~~~~ bash 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: ~~~~ markdown Version X.Y.Z ------------- Released on {Month} {Day}, {Year}. - Change description. - Another change. ~~~~ For unreleased versions: ~~~~ markdown 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 "Hongdown X.Y.Z"` - [ ] Add next version section to *CHANGES.md* - [ ] Bump version in *Cargo.toml* - [ ] 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): - [ ] Resolve *CHANGES.md* conflict: keep `main`'s unreleased section unchanged; retain all released version sections from the merged tag - [ ] Resolve *Cargo.toml* and *Cargo.lock* conflicts: keep `main`'s version - [ ] Run tests and push ### 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 "Hongdown X.Y.0"` - [ ] Add next version section to *CHANGES.md* - [ ] Bump version in *Cargo.toml* - [ ] 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 *Cargo.toml* - [ ] Commit with message `Version bump\n\n[ci skip]` - [ ] Push maintenance branch