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

1. 提升代码可追溯性：规范的提交信息可以帮助开发者快速理解每次变更的上下文和目的。
2. 自动生成变更日志：格式化的提交信息可以方便地自动生成项目的Change Log。
3. 简化代码审查：清晰的提交信息让代码审查者能够更快理解变更内容。
4. 便于问题追踪：与Issue关联的提交信息有助于跟踪问题的解决过程。

Dinky Commit Message规范详解

基本结构

Dinky项目采用三部分结构来组织提交信息：

1. Header（必需）：简明扼要地描述提交类型和主要内容
2. Body（可选）：详细说明变更内容和原因
3. Footer（可选）：用于不兼容变更说明或关闭Issue

Header部分规范

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

1. ISSUE编号

如果提交与某个Issue相关，应在方括号中注明Issue编号，如[DS-001]。若无相关Issue，可省略此部分。

2. type（提交类型）

Dinky项目定义了7种标准提交类型：

| 类型 | 说明 | 是否出现在Change Log | |----------|-----------------------------|---------------------| | feat | 新增功能 | 是 | | fix | 修复bug | 是 | | docs | 文档变更 | 否 | | style | 代码格式调整（不影响功能） | 否 | | refactor | 代码重构 | 否 | | test | 测试相关变更 | 否 | | chore | 构建过程或辅助工具变更 | 否 |

3. subject（主题）

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

• 不超过50个字符
• 使用动词开头，描述做了什么而非做了什么
• 首字母小写
• 不使用句号结尾

Body部分规范

Body部分是对变更的详细说明，建议遵循以下规则：

1. 每行不超过72个字符，避免自动换行
2. 使用现在时态（如"change"而非"changed"）
3. 说明变更动机和与之前行为的对比
4. 使用项目相关术语，保持一致性
5. 对于复杂变更，可分点说明

Footer部分规范

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

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

优秀示例分析

[DS-001][feat] add flink job monitoring dashboard

* implement real-time monitoring for running flink jobs
* add metrics collection for job throughput and latency
* create visualization dashboard using echarts
* add configuration options in admin panel

This closes #001

这个示例很好地遵循了规范：

1. Header清晰说明了Issue编号、类型和主要内容
2. Body详细列出了实现的具体功能点
3. Footer正确关闭了相关Issue

常见错误与避免方法

1. 过于简略的提交信息：如仅写"fix bug"，应具体说明修复了什么bug
2. 类型使用不当：如将新功能标记为fix，应准确选择类型
3. 格式不规范：如主题过长或使用句号结尾，应严格遵守格式要求
4. 忽略关联Issue：如提交解决特定Issue但未关联，应正确引用

工具推荐

虽然本文不提及具体工具，但开发者可以使用各种Git客户端插件或命令行工具来帮助格式化提交信息，确保符合规范。

总结

遵循Dinky项目的Commit Message规范不仅能提升个人开发效率，更能为整个项目团队带来长期收益。规范的提交信息是项目健康发展的基石，也是开发者专业素养的体现。希望每位Dinky贡献者都能认真遵守这些规范，共同维护项目的可持续发展。

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