Dinky项目Commit Message编写规范详解

Dinky项目Commit Message编写规范详解

dinky Dinky is an out-of-the-box, one-stop, real-time computing platform dedicated to the construction and practice of Unified Streaming & Batch and Unified Data Lake & Data Warehouse. Based on Apache Flink, Dinky provides the ability to connect many big data frameworks including OLAP and Data Lake. 项目地址: https://gitcode.com/gh_mirrors/di/dinky

前言

在软件开发过程中，良好的代码提交信息(Commit Message)是项目维护的重要环节。对于Dinky这样的开源项目而言，规范的提交信息能够帮助开发者更好地理解代码变更历史，提高协作效率。本文将详细介绍Dinky项目中Commit Message的编写规范，帮助开发者掌握提交信息的正确书写方式。

Commit Message的重要性

Commit Message是代码变更的"身份证"，它记录了每次提交的目的和内容。优秀的Commit Message应当：

1. 清晰说明修改内容和原因
2. 便于快速浏览和理解变更历史
3. 能够自动生成变更日志(Change Log)
4. 帮助团队成员理解代码演进过程

Dinky Commit Message规范详解

基本结构

Dinky项目的Commit Message采用三部分结构：

Header
(空行)
Body
(空行)
Footer

其中Header是必填项，Body和Footer可根据情况省略。

Header部分规范

Header部分格式为：[ISSUE编号][type] subject

1. ISSUE编号

如果本次提交与某个问题跟踪编号相关，应在方括号中注明，如[DS-001]。

2. type类型

type字段用于说明提交的类型，Dinky规定使用以下7种类型：

| 类型 | 说明 | 是否纳入Change Log | |------|------|-------------------| | feat | 新增功能 | 是 | | fix | 修复bug | 是 | | docs | 文档变更 | 否 | | style | 代码格式调整 | 否 | | refactor | 代码重构 | 否 | | test | 测试相关 | 否 | | chore | 构建或工具变更 | 否 |

3. subject主题

subject是对提交内容的简短描述，需注意：

• 不超过50个字符
• 使用动词开头，如"add"、"fix"、"update"等
• 首字母小写
• 不使用句号结尾

Body部分规范

Body部分是对提交的详细说明，应当：

1. 使用现在时态，如"change"而非"changed"
2. 每行不超过72个字符
3. 说明变更动机和实现细节
4. 使用动宾结构描述
5. 首字母不大写
6. 不使用句号结尾

Footer部分规范

Footer部分用于两种特殊情况：

1. 不兼容变更：以BREAKING CHANGE:开头，说明不兼容变更的细节和迁移方法
2. 关闭Issue：使用This closes #001格式关闭相关Issue

优秀示例分析

以下是一个符合Dinky规范的Commit Message示例：

[DS-001][docs-zh] add commit message guide

* explain commit message importance
* detail message structure and format
* provide type usage guidelines
* include practical examples for reference

This closes #001

这个示例中：

1. Header清晰标明了Issue编号、类型和简短描述
2. Body详细说明了变更内容，每行不超过72字符
3. Footer正确关闭了相关Issue
4. 整体结构完整，便于理解和跟踪

常见错误与避免方法

1. 信息过于简略：如仅写"fix bug"，应说明具体修复了什么问题
2. 类型使用不当：如将功能新增标记为fix，应准确选择type
3. 格式不规范：如缺少空行、使用过去时态等，应严格遵守格式要求
4. 描述不清晰：应使用简洁明了的语言说明变更内容

实践建议

1. 提交前使用git commit --amend检查并完善Message
2. 对于复杂变更，可先写Body再写Header
3. 团队内部定期Review Commit Message质量
4. 使用工具自动检查Message格式

总结

规范的Commit Message是Dinky项目健康发展的重要保障。通过遵循本文介绍的编写规范，开发者可以：

1. 提高代码变更的可追溯性
2. 降低团队协作成本
3. 方便生成变更日志
4. 提升项目整体质量

希望每位Dinky贡献者都能重视Commit Message的质量，共同维护项目的健康发展。

dinky Dinky is an out-of-the-box, one-stop, real-time computing platform dedicated to the construction and practice of Unified Streaming & Batch and Unified Data Lake & Data Warehouse. Based on Apache Flink, Dinky provides the ability to connect many big data frameworks including OLAP and Data Lake. 项目地址: https://gitcode.com/gh_mirrors/di/dinky