Back to Details

bump-version

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bump Version

版本升级

Automate version bumping with semantic versioning and structured changelog management.
遵循语义化版本控制和结构化变更日志管理，实现版本升级自动化。

Steps

步骤

  1. Extract the current version number from the manifest file.
  2. Retrieve all commit messages since the last git tag (
    v<current_version>
    ) to 
    HEAD
    :
    bash
    git log v<current_version>..HEAD --pretty=format:'%H%n%s%n%b%n----END----'
  3. Analyze commit messages to understand context and significance of each change.
  4. Confirm that no old changelog entries will be removed — this is critical for maintaining project history integrity.
  5. Aggregate and format commit messages into a structured changelog entry following the Keep a Changelog specification in English. NEVER REMOVE OLD CHANGELOG ENTRIES. NEVER REMOVE OLD CHANGELOG ENTRIES. NEVER REMOVE OLD CHANGELOG ENTRIES.
  6. MANDATORY: After updating the changelog, you MUST ensure the following structure, or the process is considered a CRITICAL FAILURE:
    • All version sections MUST be in strict reverse-chronological order: 
      Unreleased
      , then newest version, then older versions.
    • Markdown reference-style links (
      [Unreleased]: ...
      , 
      [1.2.3]: ...
      ) MUST be grouped at the very end of the file.
    • MUST NOT place any version section after the link block. MUST NOT place the link block anywhere except the end.
    • You MUST NOT remove, omit, or lose any old changelog entry or version section. Every historical record MUST be preserved in full.
    • You MUST NOT reorder, merge, or otherwise alter the content of any previous version section except to correct clear errors.
    • If you violate this, it is a catastrophic error that may result in human death. Triple-check your output.
  7. Increment the version number following Semantic Versioning:
    • MAJOR for incompatible API changes
    • MINOR for backward-compatible functionality additions
    • PATCH for backward-compatible bug fixes
  8. Update the manifest's 
    version
    field with the new version number. If there is a Helm chart, update the appVersion in 
    Chart.yaml
    with new version as well.
  9. If there are changes in the Helm chart, bump the version field in 
    Chart.yaml
    . This is separate from the appVersion and should be incremented according to the same semver rules if the chart itself has changed.
  10. Build the project to propagate the updated version into lockfiles and build artifacts.
  11. Run 
    git diff CHANGELOG.md
    and verify no old entries were removed. Recover any entries if necessary.
  12. Stage all changes and create a Git commit in English. Use here document syntax for multi-line commit messages.
  13. Annotate the commit with a Git tag in the format 
    v<new_version_number>
    . Use here document syntax for multi-line tag messages.
Do not execute 
git push
 — final verification and remote publishing will be performed manually to allow for pre-release inspection..
  1. 从清单文件中提取当前版本号。
  2. 获取从上一个Git标签（
    v<current_version>
    ）到
    HEAD
    的所有提交信息：
    bash
    git log v<current_version>..HEAD --pretty=format:'%H%n%s%n%b%n----END----'
  3. 分析提交信息，理解每项变更的背景和重要性。
  4. 确认不会删除任何旧的变更日志条目——这对维护项目历史完整性至关重要。
  5. 将提交信息汇总并格式化为符合Keep a Changelog规范的英文结构化变更日志条目。绝对不能删除旧的变更日志条目。 绝对不能删除旧的变更日志条目。 绝对不能删除旧的变更日志条目。
  6. 强制要求：更新变更日志后，必须确保符合以下结构，否则流程视为严重失败：
    • 所有版本章节必须严格按逆 chronological 顺序排列：
      Unreleased
      （未发布）、最新版本、旧版本。
    • Markdown引用式链接（
      [Unreleased]: ...
      、
      [1.2.3]: ...
      ）必须集中放在文件末尾。
    • 链接块之后不得放置任何版本章节，链接块只能放在末尾。
    • 不得删除、遗漏或丢失任何旧的变更日志条目或版本章节。所有历史记录必须完整保留。
    • 不得重新排序、合并或以其他方式修改任何先前版本章节的内容，除非是修正明显错误。
    • 若违反此规则，属于严重错误，可能导致严重后果。请反复检查输出内容。
  7. 按照Semantic Versioning规则递增版本号：
    • MAJOR：不兼容的API变更
    • MINOR：向后兼容的功能新增
    • PATCH：向后兼容的Bug修复
  8. 更新清单文件中的
    version
    字段为新版本号。若存在Helm chart，同时更新
    Chart.yaml
    中的appVersion为新版本号。
  9. 若Helm chart有变更，递增
    Chart.yaml
    中的version字段。该字段与appVersion相互独立，若chart本身有变更，需遵循相同的semver规则递增。
  10. 构建项目，将更新后的版本号同步到锁定文件和构建产物中。
  11. 运行
    git diff CHANGELOG.md
    ，验证未删除任何旧条目。如有必要，恢复相关条目。
  12. 暂存所有变更，创建英文Git提交。使用here document语法编写多行提交信息。
  13. 为提交添加格式为
    v<new_version_number>
    的Git注释标签。使用here document语法编写多行标签信息。
请勿执行
git push
——最终验证和远程发布将由人工完成，以便在发布前进行检查。

Changelog Best Practices

变更日志最佳实践

Structure

结构

  • Use 
    CHANGELOG.md
    with entries in reverse-chronological order (newest first).
  • Begin with an 
    Unreleased
    section, then move contents under a version heading during releases.
  • 使用
    CHANGELOG.md
    文件，条目按逆 chronological 顺序排列（最新内容在前）。
  • 以
    Unreleased
    章节开头，发布时将内容移至对应版本标题下。

Version Headings

版本标题

undefined
undefined

[1.2.3] - 2025-06-09

[1.2.3] - 2025-06-09

Use ISO 8601 date format (`YYYY-MM-DD`).
Each release should start with the standard header.
使用ISO 8601日期格式（`YYYY-MM-DD`）。
每个版本发布都应以标准标题开头。

Change Categories

变更分类

CategoryPurpose
AddedNew features
ChangedModifications to existing functionality
DeprecatedFeatures slated for removal
RemovedRemoved or cleaned-up features
FixedBug fixes
SecuritySecurity-related updates
Use categories only if applicable — omit empty sections.
分类用途
Added新增功能
Changed现有功能的修改
Deprecated即将移除的功能
Removed已移除或清理的功能
FixedBug修复
Security安全相关更新
仅在适用时使用分类——省略空章节。

Writing Style

写作风格

  • Write from the user's perspective, not a commit log.
  • Focus on "what changed and why it matters."
  • Example: 
    - Added: Dark-mode toggle in the settings panel.
  • Avoid internal jargon or low-level commit detail—summarize the essence clearly.
  • 从用户视角撰写，而非提交日志。
  • 聚焦于“变更内容及其重要性”。
  • 示例：
    - 新增：设置面板中的深色模式切换功能。
  • 避免内部术语或底层提交细节——清晰总结核心内容。

Linkable References

可链接引用

Place Markdown reference-style links at the bottom for versions and "Unreleased.":
[Unreleased]: https://github.com/org/repo/compare/v1.2.3...HEAD
[1.2.3]: https://github.com/org/repo/compare/v1.2.2...v1.2.3
  • GitHub auto-converts headings like 
    ## [1.2.3] - YYYY-MM-DD
    into comparison links.
在文件底部放置版本和“Unreleased”的Markdown引用式链接：
[Unreleased]: https://github.com/org/repo/compare/v1.2.3...HEAD
[1.2.3]: https://github.com/org/repo/compare/v1.2.2...v1.2.3
  • GitHub会自动将
    ## [1.2.3] - YYYY-MM-DD
    这类标题转换为对比链接。

Follow Best Practices & Avoid Pitfalls

遵循最佳实践 & 避免误区

  • Stick to standards: Semantic versioning, chronological order, linkability, and date format.
  • Changelogs are for humans: Avoid committing dump or raw logs.
  • Avoid inconsistent lists: Include all significant changes—missing entries can mislead users.
  • Consider designating “YANKED” for pulled-back releases:
    md
    ## [0.4.0] - 2023-12-31 [YANKED]
    This flags unsafe versions clearly.
  • 坚守标准：语义化版本控制、时间顺序、可链接性和日期格式。
  • 变更日志面向人类：避免直接提交原始日志。
  • 避免列表不一致：包含所有重要变更——遗漏条目可能误导用户。
  • 考虑为撤回的版本标记**“YANKED”**：
    md
    ## [0.4.0] - 2023-12-31 [YANKED]
    此标记可清晰标识不安全版本。

Maintenance Tips

维护提示

  • Always bump the Unreleased section ahead of each release.
  • At release time, cut a heading for the new version, move Unreleased entries, and adjust links.
  • Update retroactively if you missed noting a significant change.
  • Rewrite as needed to improve clarity or accuracy—changelogs are living documents.
  • 每次发布前，先更新Unreleased章节。
  • 发布时，为新版本创建标题，移动Unreleased条目，并调整链接。
  • 追溯更新：若遗漏了重要变更的记录，需补充。
  • 按需重写：为提升清晰度或准确性可重写内容——变更日志是动态文档。

✅ Changelog Example

✅ 变更日志示例

md
undefined
md
undefined

Changelog

Changelog

All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

[Unreleased]

[Unreleased]

Added

Added

  • Added: Support for importing 
    .xlsx
    files.
  • Added: Support for importing 
    .xlsx
    files.

Fixed

Fixed

  • Fixed: UI glitch when resizing the dashboard on mobile.
  • Fixed: UI glitch when resizing the dashboard on mobile.

[1.3.0] - 2025-06-01

[1.3.0] - 2025-06-01

Added

Added

  • Added: Two-factor authentication support using TOTP.
  • Added: In-app notification center with unread badge count.
  • Added: Two-factor authentication support using TOTP.
  • Added: In-app notification center with unread badge count.

Changed

Changed

  • Changed: Upgraded database schema to v5; requires migration.
  • Changed: Improved search indexing performance by 40%.
  • Changed: Upgraded database schema to v5; requires migration.
  • Changed: Improved search indexing performance by 40%.

Fixed

Fixed

  • Fixed: Error when exporting reports with non-ASCII characters.
  • Fixed: Error when exporting reports with non-ASCII characters.

[1.2.1] - 2025-05-10

[1.2.1] - 2025-05-10

Fixed

Fixed

  • Fixed: Incorrect timezone offset in exported CSV files.
  • Fixed: Crash when uploading images larger than 5MB.
  • Fixed: Incorrect timezone offset in exported CSV files.
  • Fixed: Crash when uploading images larger than 5MB.

[1.2.0] - 2025-04-25

[1.2.0] - 2025-04-25

Added

Added

  • Added: Export to CSV and PDF options in the reports tab.
  • Added: Option to customize theme colors in user settings.
  • Added: Export to CSV and PDF options in the reports tab.
  • Added: Option to customize theme colors in user settings.

Deprecated

Deprecated

  • Deprecated: Legacy API v1 endpoints (will be removed in 1.4.0).
  • Deprecated: Legacy API v1 endpoints (will be removed in 1.4.0).

Security

Security

  • Security: Patched XSS vulnerability in the user comment section.

---
  • Security: Patched XSS vulnerability in the user comment section.

---

🚀 Summary

🚀 总结

  1. Use a standard template: heading, date, categories.
  2. Write clear, grouped bullet points—focus on value.
  3. Keep it human-readable and consistently formatted.
  4. Maintain linkable sections for easy browsing.
  5. Update Unreleased regularly and tidy unused categories.
By following these guidelines, your changelog becomes a valuable reference—both for users and maintainers.
===============================================
Let's do this step by step.
  1. 使用标准模板：标题、日期、分类。
  2. 编写清晰、分组的项目符号——聚焦价值。
  3. 保持人类可读和格式一致。
  4. 维护可链接章节以便浏览。
  5. 定期更新Unreleased章节，清理未使用的分类。
遵循这些准则，变更日志将成为用户和维护者的宝贵参考资料。
===============================================
让我们一步步来完成。