https://github.com/pj-568/git-commit-regulation

提交说明规范 | Regulation about the format of commit messages
https://github.com/pj-568/git-commit-regulation

Last synced: 16 days ago
JSON representation

提交说明规范 | Regulation about the format of commit messages

• Host: GitHub
• URL: https://github.com/pj-568/git-commit-regulation
• Owner: PJ-568
• License: cc-by-sa-4.0
• Created: 2024-10-27T15:44:23.000Z (3 months ago)
• Default Branch: master
• Last Pushed: 2024-11-17T05:01:36.000Z (2 months ago)
• Last Synced: 2024-11-17T06:17:26.342Z (2 months ago)
• Homepage:
• Size: 13.7 KB
• Stars: 0
• Watchers: 1
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# PJ568 提交说明规范 `v 0.1.4`

本规范旨在格式化提交说明，以在方便阅读理解的同时，保证其能被程序一致地解析。

简见[简例](#简例)。

## 格式

提交的格式的构成：

- 标题：标题须为单行文本，并包含：

  - [类型](#类型)：具体提交类型；

  - [范围](#范围)（可选）：提交的对象所属范围；

  - [摘要](#摘要)：描述提交内容的短句；

- [描述](#描述)（可选）：可包含多行详细信息的文本。

### 简例

详尽的提交示例如下：

```markdown

【修复，认证】解决登录界面的输入验证问题

修复了登录界面中输入验证逻辑的问题，确保用户输入的用户名和密码格式正确。

相关问题编号：

#568

```

最小提交示例如下：

```markdown

【修复】解决登录界面的输入验证问题

```

## 内容

尽量使每一次提交都只针对单个目标功能的修改。

### 多语言混排

汉字和阿拉伯数字、字母和非汉语符号之间应用空格分隔。

以下是几个示例：

1. **简单的句子**：

   - **原始**：`今天是2023年10月1日，天气晴朗。`

   - **改进**：`今天是 2023 年 10 月 1 日，天气晴朗。`

2. **包含英文单词**：

   - **原始**：`我们使用Python编写代码。`

   - **改进**：`我们使用 Python 编写代码。`

3. **包含特殊符号**：

   - **原始**：`项目截止日期是2023-10-31。`

   - **改进**：`项目截止日期是 2023-10-31。`

4. **包含变量名**：

   - **原始**：`变量name的值是"张三"。`

   - **改进**：`变量 name 的值是 "张三"。`

5. **包含数学公式**：

   - **原始**：`计算结果是1+2=3。`

   - **改进**：`计算结果是 1 + 2 = 3。`

6. **包含网址**：

   - **原始**：`访问https://example.com获取更多信息。`

   - **改进**：`访问 https://example.com 获取更多信息。`

#### 原因

- **提高可读性**：在汉字和阿拉伯数字、字母及非汉语符号之间加空格，可以明显区分不同的元素，使句子结构更加清晰，提高可读性。

- **符合规范**：遵循这一规则可以使文档更加规范，符合国际化的写作标准，便于不同语言背景的读者理解。

- **避免歧义**：在某些情况下，不加空格可能会导致歧义和编码错误，加空格可以避免这种问题。

### 类型

**类型**是提交说明的中心内容，也是程序解析提交说明的依据。

类型的长度为二个汉字。类型必须被包含在实心方头括号（鱼尾括号：`【】`）中，以防与[摘要](#摘要)混淆。

一切标题必须包含一个类型，且类型的内容必须是以下之一：

|内容|代码相关|描述|

|:-:|:-:|:--|

|初始|视情况|当且仅当仓库第一次提交。|

|更改|是|重大改变或移除功能。|

|新增|是|影响使用或生产的新功能。|

|修复|是|对现有错误的修复。|

|格式|视情况|不影响功能和生产的代码格式、文档或注释更改。|

|文档|否|对文档、自述（Readme）等的更改。|

|测试|是|新增或编辑测试。|

|维护|否|对诸如模板文件、样式表等非生产代码更改。|

以上类型按照优先级从高到低排列。

当提交符合多项类型时，代码相关的项目应使用契合提交代码相关性的高优先级的类型；

完全代码无关的项目可忽略代码相关性。

需注意相应类型的提交和[版本控制](https://semver.org/lang/zh-CN)间的对应关系，如：

- `【更改】`：提升主版本号；

- `【新增】`：提升次版本号；

- 其它：提升修订号。

简例：

```markdown

【修复，核心】解决内存泄漏问题

```

```markdown

【格式】修改脚本的语法风格

```

```markdown

【维护】更新默认配置

```

### 范围

范围由项目负责人划分，并确保一致性。

项目负责人应在项目文档中定义范围列表。

大部分情况下，项目可以用子目录、包、模块等单位划分。

添加新范围要经过深思熟虑，而绝不应是提交时的心血来潮。

范围位于实心方头括号内，紧接在[类型](#类型)内容之后，与[类型](#类型)内容以逗号（`，`）分隔。

范围是可选的：

- 当项目规模较小时可不使用范围。当项目达到一定规模时引入范围。

- 当提交不限于单个范围或与任意范围无关时可不使用范围。

#### 范围的作用

范围在提交说明中的作用是明确变更位置、增强可追溯性、提高沟通效率、支持自动化工具和保持一致性。通过合理使用范围，可以显著提升代码库的可维护性和团队协作效率。

其中：

1. **明确变更位置**：

   - **作用**：范围明确指出了提交影响的具体部分，帮助团队成员快速了解代码变更的位置。

   - **原因**：在大型项目中，代码库通常被划分为多个子目录、包或模块。通过指定范围，维护者可以迅速定位到变更的具体位置，提高审查和调试的效率。

2. **增强可追溯性**：

   - **作用**：范围信息有助于追踪代码变更的历史记录，便于后续的维护和审计。

   - **原因**：当需要回溯某个功能或模块的历史变更时，范围信息可以提供重要的上下文，帮助开发者快速找到相关提交记录。

3. **提高沟通效率**：

   - **作用**：范围信息使得团队成员之间的沟通更加高效，减少不必要的讨论和误解。

   - **原因**：通过明确的范围标识，团队成员可以快速理解提交的背景和目的，避免因信息不明确而导致的沟通障碍。

4. **支持自动化工具**：

   - **作用**：范围信息可以被自动化工具解析和利用，用于生成变更日志、统计报告等。

   - **原因**：许多自动化工具和持续集成系统可以根据提交范围生成详细的变更日志，帮助团队更好地管理和监控项目的进展。

5. **保持一致性**：

   - **作用**：范围由项目负责人统一定义和管理，确保整个项目的一致性。

   - **原因**：项目负责人在项目文档中定义范围列表，确保所有团队成员遵循相同的规范，避免因个人偏好导致的混乱。

#### 范围示例

假设一个项目有以下范围定义：

- `核心`：核心模块

- `认证`：认证模块

- `UI`：用户界面模块

- `API`：API 接口模块

**提交示例**：

- **单一范围提交**：

  ```markdown

  【修复，核心】解决内存泄漏问题

  ```

- **多范围提交**（选择最相关的范围）：

  ```markdown

  【新增，UI】添加用户设置页面

  ```

### 摘要

简练地描述更改，尽量不超过 30 个汉字或 60 个字符。超出的重要信息应写入[描述](#描述)。

用祈使句，如：`添加功能至目标`、`更新某文件`。

请勿直接引用如 `#568` 的问题编号，这会降低可读性且导致项目难以溯源。请将问题编号添加至[描述](#描述)。

例子：

1. **修复错误**：

   ```markdown

   【修复】解决登录界面的输入验证问题

   ```

2. **新增功能**：

   ```markdown

   【新增】添加用户设置页面

   ```

3. **代码优化**：

   ```markdown

   【格式】调整代码风格，统一缩进

   ```

4. **文档更新**：

   ```markdown

   【文档】更新项目 README 文件

   ```

5. **测试用例**：

   ```markdown

   【测试】增加用户注册功能的测试用例

   ```

6. **性能优化**：

   ```markdown

   【优化】提升数据加载速度

   ```

7. **安全修复**：

   ```markdown

   【修复】修复 SQL 注入漏洞

   ```

8. **配置更新**：

   ```markdown

   【维护】更新默认配置文件

   ```

### 描述

描述是可选的。

描述应紧接在[摘要](#摘要)后，与[摘要](#摘要)用两个换行符相隔。

用祈使句。

描述可包含以下内容：

- 提交的理由；

- 在代码中未标明的潜在因素，如副作用或迁移提示；

- 注意事项；

- 相关问题编号。

## 许可

本规范遵循 [CC BY-SA 4.0](LICENSE) 许可协议发布。