release-ready

name	release-ready
description	Prepare a release by verifying version consistency, generating release notes, updating help docs, and running quality checks. Use when on a release branch (vX.X.X-release) and ready to finalize a version for deployment.
license	MIT
metadata	{"author":"rozx","version":"1.0"}

Prepare the current branch for release. This is a multi-step workflow that ensures version consistency, generates documentation, and validates code quality.

All generated content (release notes, help docs) MUST be written in Chinese (中文).

---

Step 1: Version Consistency Check

1. Determine the current branch name using git branch --show-current.

   • Expected branch format: vX.X.X-release (e.g., v0.9.3-release).
   • Extract the target version from the branch name (e.g., 0.9.3 from v0.9.3-release).

2. Read package.json and check the version field.

3. If the version does NOT match the branch target version:

   • Run bun bump <version> to update. For example: bun bump 0.9.3.
   • This updates both package.json and src/constants/version.ts.
   • Verify the update was successful by re-reading both files.

4. If the version already matches, report success and move on.

---

Step 2: Generate Release Notes

1. Identify the previous release version by finding the latest git tag:

   git tag --sort=-v:refname | head -5
   

   The previous version tag is typically vX.X.X (e.g., v0.9.2).

2. Gather all changes between the previous release and the current branch:

   git log <previous-tag>..HEAD --oneline
   git diff <previous-tag>..HEAD --stat
   

   Also read individual commit messages for detail when needed:

   git log <previous-tag>..HEAD --pretty=format:"%h %s"
   

3. Read existing release notes for format reference:

   • Read at least one recent file from public/releaseNotes/ (e.g., RELEASE_NOTES_v0.9.2.md).
   • Follow the same structure and formatting conventions.

4. Create the new release notes file at:

   public/releaseNotes/RELEASE_NOTES_v<VERSION>.md
   

   The release note MUST follow this structure:

   # 发布说明 - vX.X.X
   
   ## 版本信息
   
   - **版本号**: X.X.X
   - **发布日期**: YYYY年M月D日
   - **基于版本**: vX.X.X (previous version)
   
   ---
   
   ## <emoji> <Feature Category in Chinese> (<English subtitle>)
   
   <Detailed description of changes in Chinese>
   
   ---
   
   ## 📝 问题修复
   
   - 修复：<description in Chinese>
   
   ---
   
   ## 📚 相关文档
   
   - **<Doc Title>**: `help/<filename>.md`
   
   ---
   
   _本文档基于 git changes vX.X.X..vX.X.X_
   

   Guidelines:

   • Group related changes into logical categories with emoji headers.
   • Use descriptive Chinese text for all content.
   • Include English subtitles in parentheses for category headers.
   • Be specific about what changed and why it matters to users.
   • Reference related help docs at the bottom.

5. Update public/help/index.json:

   • Add a new entry for the release note at the top of the release notes section (after the help doc entries, before other release note entries):

     {
       "id": "vX.X.X",
       "title": "vX.X.X",
       "file": "RELEASE_NOTES_vX.X.X.md",
       "path": "releaseNotes",
       "category": "更新日志",
       "description": "<Brief summary of key changes in Chinese>"
     }
     

   • The new entry should be inserted before the existing release note entries (newest first).

---

Step 3: Update Help Documentation

1. Review the changes identified in Step 2 and determine if any help docs need updating.

   • New features may require new help docs or updates to existing ones.
   • Read existing help docs in public/help/ to understand current coverage.

2. For each help doc that needs updating:

   • Read the existing file first.
   • Add or update sections relevant to the new features.
   • Maintain the existing format and style.
   • All content MUST be in Chinese.

3. If a new help doc is needed:

   • Create it in public/help/ following the naming convention of existing files.
   • Add a corresponding entry to public/help/index.json in the appropriate category:

     {
       "id": "<kebab-case-id>",
       "title": "<Chinese title>",
       "file": "<filename>.md",
       "path": "help",
       "category": "<使用指南 or 书籍详情页>",
       "description": "<Brief description in Chinese>"
     }
     

4. If no help doc changes are needed, explicitly state so and explain why.

---

Step 4: Quality Checks

1. Run type checking:

   bun run type-check
   

   • If errors are found, fix them before proceeding.
   • Report all errors and fixes applied.

2. Run linting:

   bun run lint
   

   • If errors are found, fix them.
   • Warnings should be reviewed but may be acceptable.

3. Report final status:

   • Summarize all changes made during this release preparation.
   • List all files created or modified.
   • Confirm the release is ready (or report remaining issues).

---

Summary Output

After completing all steps, provide a summary:

📋 Release Preparation Summary - vX.X.X
────────────────────────────────────────
✅ Version: package.json and version.ts updated to X.X.X
✅ Release Notes: public/releaseNotes/RELEASE_NOTES_vX.X.X.md created
✅ Help Docs: [updated/no changes needed]
✅ index.json: Updated with new entries
✅ Type Check: Passed
✅ Lint: Passed

Files changed:
  - <list of files>

Ready for release! 🚀