0
代码
代码
Issues
Pull Requests
讨论
Wiki
分析
0
Ggyangedocs(Docs): optimize the docs structure
eec718bb创建于 4月22日历史提交

社区 Changelog 规范

本规范基于全球开源社区通用的 Keep a Changelog 1.1.0 标准制定，兼容语义化版本（Semantic Versioning 2.0.0），适用于开源项目、社区产品、技术组件的变更日志维护，核心目标是让用户、贡献者清晰感知版本间的关键变更，降低社区协作与升级成本。

一、核心指导原则

  1. 以人为本：Changelog 是写给人看的，而非机器，禁止直接堆砌 Git 提交记录、内部技术实现细节。
  2. 全量可追溯：每个正式发布版本必须有独立的变更条目，无遗漏记录对用户有影响的变更。
  3. 分类清晰：同类型变更必须分组归类，保持格式统一、语义一致。
  4. 时序规范：最新版本在前，旧版本在后，按发布时间倒序排列。
  5. 可链接可跳转：版本、章节、关联 Issue/PR 均支持锚点跳转，便于精准定位。
  6. 透明兼容：必须明确标注破坏性变更、弃用功能、安全修复，提前告知用户风险与适配成本。

二、基础文件规范

规范项 强制要求 错误示例 正确示例
文件名 必须为全大写的 CHANGELOG.md，固定存放于项目仓库根目录 changelog.md、ChangeLog.md、CHANGELOG.MD CHANGELOG.md
文件格式 必须使用标准 Markdown 语法，纯文本编写，禁止二进制/富文本格式 Word文档、HTML格式、自定义富文本标签 标准 Markdown 语法
编码格式 统一使用 UTF-8 无 BOM 编码，换行符兼容 Unix/Windows 格式 GBK 编码、带 BOM 的 UTF-8 UTF-8 无 BOM 编码

三、核心结构规范

Changelog 整体结构固定，从上到下依次为：文件头部 → 未发布变更区 → 已发布版本区 → 版本对比链接区，不可随意调换顺序。

1. 文件头部（强制）

位于文件最顶端，必须包含3个核心要素：标题、适用范围、规范与版本声明，示例如下：

# Changelog

本文件记录了 {项目名称} 所有值得关注的变更内容。

本日志格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 规范编写，
项目版本遵循 [语义化版本 2.0.0](https://semver.org/lang/zh-CN/) 标准。

面向国际社区的项目，需提供英文原版声明，可附加多语言翻译；若项目有特殊版本规则，需在此处补充说明。

2. 未发布变更区 [Unreleased]（强烈推荐）

位于头部之后、所有正式版本之前，用于归集开发中、尚未发布的变更，避免发布前突击整理日志。

## [Unreleased]

### Added
- 新增 XX 功能模块，支持 XX 能力

### Fixed
- 修复 XX 场景下的崩溃问题

版本发布时，直接将 [Unreleased] 改为对应版本号 + 发布日期，下方新增空白的 [Unreleased] 区块即可；可在此处提前标注预发布版本的破坏性变更、弃用计划。

3. 已发布版本区（强制）

这是 Changelog 的核心主体，每个独立版本对应一个二级标题区块，格式严格遵循：

## [版本号] - 发布日期
  • 版本号：严格遵循语义化版本 MAJOR.MINOR.PATCH，如 1.2.0、2.0.0，禁止前缀 v 或其他自定义字符
  • 发布日期：强制使用 ISO 8601 标准格式 YYYY-MM-DD，如 2026-04-09，禁止简写、非标准分隔符

每个版本区块内，必须按变更类型进行三级标题分组，同类型变更使用无序列表逐条记录。

4. 版本对比链接区（强制）

位于文件最底部，为每个版本添加版本间差异对比链接，便于用户查看完整代码变更，格式示例：

[Unreleased]: https://gitcode.com/{组织名}/{仓库名}/compare/v1.2.0...HEAD
[1.2.0]: https://gitcode.com/{组织名}/{仓库名}/compare/v1.1.0...v1.2.0
[1.1.0]: https://gitcode.com/{组织名}/{仓库名}/compare/v1.0.0...v1.1.0
[1.0.0]: https://gitcode.com/{组织名}/{仓库名}/releases/tag/v1.0.0

链接地址需与版本号一一对应，确保可正常访问；首个正式版本直接链接到 Release 页面，无需对比链接。

四、变更类型分类规范

变更类型分为 7 个标准强制类型和 1 个社区扩展可选类型，必须严格按优先级排序，不可随意调换顺序、自定义类型名称，确保全社区认知统一。

1. 标准强制类型（优先级从高到低）

类型（英文 / 中文） 适用场景 编写要点
Added / 新增 新增功能、特性、模块、API、配置项、依赖等 明确功能的核心能力、适用场景，说明用户可获得的价值
Changed / 变更 现有功能的逻辑、行为、UI、API 入参 / 出参、依赖版本、默认配置的修改 清晰说明「旧行为→新行为」的变化，破坏性变更必须在条目最开头用【破坏性变更】高亮标注，并补充适配指引
Deprecated / 弃用 计划在未来版本中移除的功能、API、配置项 明确弃用原因、计划移除的版本，推荐替代方案，提醒用户提前适配
Removed / 移除 本版本中正式移除的、已在之前版本标记为弃用的功能、API、配置项、依赖 明确移除的内容、影响范围，补充完整的替代方案与升级步骤
Fixed / 修复 各类 Bug、异常、兼容性问题的修复 清晰描述问题场景、影响范围、修复结果，关联对应的 Issue/PR 编号
Security / 安全 安全漏洞、隐私合规相关的修复与优化 明确漏洞等级、影响版本、修复结果，关联 CVE 编号、安全公告链接，提醒用户紧急升级
Documentation / 文档 对用户使用有影响的文档变更，如新增使用教程、最佳实践、API 文档补全、重大勘误等 明确文档变更内容，说明对用户的影响，如新增使用指南、API 文档完善等

2. 社区扩展可选类型

仅当变更内容无法归入上述 7 类，且对用户有明确影响时使用，禁止滥用扩展类型覆盖标准类型：

  • Performance / 性能：不改变功能逻辑的性能优化，如接口响应速度、内存占用、启动速度优化等

五、条目编写规范

单条内容要求

每条变更控制在 1-2 句话，简洁完整，使用陈述句，避免模糊化、无意义的描述。

❌ 错误示例：优化了部分体验、修复了一些 bug、提升了性能

✅ 正确示例：优化了列表分页加载速度，峰值加载耗时降低 40%；修复了Openharmony 6.0系统下图片上传失败的问题，关联 Issue #123

视角要求

始终站在社区用户 / 贡献者视角编写，聚焦「变更对用户的影响」，而非内部技术实现细节。

❌ 错误示例：重构了 XX 类的代码结构，调整了 XX 变量的命名

✅ 正确示例：重构了 XX 模块的底层逻辑，接口调用成功率从 99.2% 提升至 99.95%，无 API 使用变更

关联规范

社区协作场景下，建议每条变更末尾关联对应的 PR 编号、Issue 编号、贡献者 ID，提升可追溯性，同时尊重社区贡献。

示例：新增用户角色权限批量管理功能，by @contributor-name，关联 PR #456

破坏性变更规范

  1. 必须在变更条目最开头用【破坏性变更】高亮标注，不可隐藏在普通条目中
  2. 大版本（MAJOR）升级的破坏性变更，需在版本标题下方单独增加「Breaking Changes」区块，集中说明
  3. 必须补充完整的升级适配指南，明确旧方案→新方案的替换步骤，降低用户升级成本

六、社区维护最佳实践

  1. 随开发同步更新：在 PR 合并时同步更新 Changelog 条目，而非版本发布前集中补写，避免遗漏关键变更，降低维护成本。
  2. 区分「用户可见」与「内部变更」：仅记录对社区用户、下游使用者有影响的变更，无需记录内部代码格式化、CI/CD 配置调整、开发依赖小版本升级等无感知变更。
  3. 版本发布一致性：Changelog 中记录的版本号、发布日期，必须与仓库 Release 标签、包管理平台发布版本完全一致。
  4. 多语言适配：面向多语言社区的项目，可提供 CHANGELOG-zh-CN.md、CHANGELOG-en.md 等多语言版本，确保核心变更内容完全一致。
  5. 社区触达：版本发布时，将对应版本的 Changelog 内容同步到 Release 说明、社区公告、用户群等渠道，提升变更的触达率。

七、完整规范模板

# Changelog

本文件记录了 Demo-Project 所有值得关注的变更内容。

本日志格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 规范编写，
项目版本遵循 [语义化版本 2.0.0](https://semver.org/lang/zh-CN/) 标准。

## [Unreleased]

### Added
- 新增数据批量导出为Excel功能，支持自定义字段筛选
- 新增Webhook回调能力，支持事件触发实时推送

### Deprecated
- 弃用旧版 `/v1/user/list` 接口，计划在2.0.0版本正式移除，推荐使用 `/v2/user/page` 接口

## [1.2.0] - 2026-03-15

### 【Breaking Changes】
1. 调整了用户认证接口的签名算法，旧版签名方式不再兼容
2. 移除了已弃用的配置项 `timeout_old`，需替换为 `request_timeout`

### Added
- 新增用户二次验证功能，支持短信/邮箱验证码双渠道，by @community-contributor，关联 PR #234
- 新增暗黑模式主题，支持系统主题自动切换

### Changed
- 【破坏性变更】重构用户认证接口签名算法，由MD5升级为SHA256，提升接口安全性
- 优化首页列表渲染逻辑，首屏加载速度提升30%

### Fixed
- 修复了分页查询时页码超出范围返回异常的问题，关联 Issue #189
- 修复了Firefox浏览器下表单提交按钮点击无响应的兼容性问题

### Security
- 修复了越权访问用户信息的高危漏洞，影响版本：1.0.0-1.1.0，建议所有用户升级至当前版本
- 升级了敏感依赖包 `axios` 至 1.7.9 版本，修复已知安全漏洞

### Deprecated
- 弃用配置项 `timeout_old`，计划在2.0.0版本移除，推荐使用 `request_timeout` 配置请求超时时间

## [1.1.0] - 2026-02-10

### Added
- 新增用户个人资料编辑功能
- 新增操作日志查询能力，支持按时间、操作类型筛选

### Fixed
- 修复了登录态过期后无法自动跳转到登录页的问题
- 修复了数据统计图表数值显示异常的问题

## [1.0.0] - 2026-01-01

### Added
- 项目正式发布，核心功能包含用户管理、数据查询、报表生成
- 配套发布官方使用文档、API接口文档

[Unreleased]: https://gitcode.com/OpenHarmony-RN/ohos_react_native/compare/v1.2.0...HEAD
[1.2.0]: https://gitcode.com/OpenHarmony-RN/ohos_react_native/compare/v1.1.0...v1.2.0
[1.1.0]: https://gitcode.com/OpenHarmony-RN/ohos_react_native/compare/v1.0.0...v1.1.0
[1.0.0]: https://gitcode.com/OpenHarmony-RN/ohos_react_native/releases/tag/v1.0.0