文章

Contributing Guidelines 开发指南

Posted 2024-09-14 Updated 2024-11- 4
By 昼阳
24~31 min read

撰写给工作室的代码贡献规范

本项目开发必须遵循以下规范。

请注意， 英语是开发过程中唯一允许使用的语言 ，比如代码、注释、 Git message 和代码内文档。
因为复杂字符存在编码问题，在整个开发协作过程中应当避免。

代码风格

前端

WIP

后端

后端开发编写代码参考

Java开发手册（嵩山版）.pdf

开发者必须严格遵守上面准则。

Git 工作流

我们使用 git 作为我们的版本控制系统，并遵循下面的工作流程。

  1. 在修复 bug 或实现新功能之前，开发者应首先 创建一个新 issue 。
    发起新 issue 时使用 该模板 。
  2. 处理 issue 时，应当 创建一个新分支 ，分支相关规范如下所述。
  3. 若开发取得进展，请立即提交更改。
    具体地，当 一个功能开发完毕后，就提交更改 。
    Git 的提交信息请遵守 如下规范 。
  4. 解决 issue 后，请为该分支 创建一个 Pull Request 请求合并代码 。
    参阅 如下详述 。
  5. 在创建 Pull Request 后，开发者应首先 自我审查 代码。
    Pull Request 指定的代码审查者而后将会审查你的代码，如果没有问题将会进行合并。
    开发者可能需要代码审查者进行进一步讨论。

分支规范

我们主要使用三种分支：

  • main ：主分支
    main 分支应当始终处于 稳定 状态，是新版本的基准分支。
    main 分支的合并仅接受带有 [Release] 标签的 Pull Request 。
    紧急修复除外，应当直接合并到 main 分支中。
    main 分支受到严格保护。
    除了仓库的初始化外，没有人可以直接推送到主分支。
  • dev : 开发的基准分支
    dev 分支是开发的基准分支。
    新功能和 Bug 修复会通过 Pull Request 被合并到 dev 分支中。
    当 dev 分支稳定后，需要发布新版本时，
    仓库维护者应当创建一个带有 [Release] 标签的 Pull Request ，
    将 dev 分支合并到 main 分支中。
    dev 分支收到保护，
    只有仓库维护者或具有权限的人才能直接推送至 dev 分支。
  • 其他开发分支：用于开发具体功能，从 dev 分支创建。

开发分支的命名约定为：

<类型>/<关联 issue 编号>-<简短描述>

短划线（ - ）用于分隔问题编号和简短描述，
下划线（ _ ）应用于分隔简短描述中的单词。

类型

开发分支主要有 6 种类型：

  • hotfix : 对 main 分支的 紧急修复
    当在 main 中遇到应该立即修复的 bug 时，应该创建一个 hotfix 分支。
    修复后，该分支应直接合并到 main 分支中。
  • feature : 新功能
    当实现新功能时，应创建 feature 分支。
    实现后，应将分支合并到 dev 分支中。
  • bugfix : Bug 修复
    修复 bug 时，应创建 bugfix 分支。
    修复 bug 后，应将该分支合并到 `dev`` 分支中。
  • documentation : 项目 文档
    在编写或修补文档时，应创建documentation分支。
    使用 documentation 分支时，开发者不应更改代码。
    文档完成后，该分支应合并到 dev 中。
  • chore : 除上述以外的其他 杂项工作
    在进行其他杂项任务时，应该创建一个 chore 分支。
    非新功能、 bug 修复或文档修补的更改，
    例如工作区配置、CI/CD 配置等，均属于杂务。
    完成后，该分支应该合并到 dev 分支中。

关联 issue 编号

<关联 issue 编号> 是 Github Issue 中 issue 的编号。
在开发新功能或修复 bug 之前，应当先创建一个新 issue 。

主题

<主题> 是问题的简短描述。
为了规避潜在的编码问题，应使用 英语 。
描述应 尽可能简短 ，以英文小短句为主。

Git 提交信息

制定此标准时，参考了 这篇文章
和 Google Blocky Git Commit Guide 。

提交信息的格式为：

<类型>(<作用域>): <主题>

<正文>

<脚注>

类型

<类型> 是更改的分类， 应该是以下分类之一 ：

  • feat : 新功能或特性实现
  • fix: bug 修复
  • chore : 与修复或功能无关的更改，
    并且不修改源代码或测试文件（例如更新依赖关系）
  • refactor : 代码重构，既没有新增功能也没有修复 bug
  • docs : 更新文档，如 README 或其他 Markdow 文件
  • style : 不影响代码含义的更改，
    可能与代码格式有关，如缩进问题、缺少分号等。
  • test : 包括新的或纠正以前的测试
  • perf : 性能改进
  • ci : 持续集成（ CI/CD ）相关
  • build : 影响构建系统或外部依赖关系的更改
  • revert : 回退之前的提交

补充美化版本：

🎉 init: 初始化

🚀 release: 发布新版本

🎨 style: 代码风格修改（不影响代码运行的变动）

✨ feat: 添加新功能

🐛 fix: 修复 bug

📝 docs: 对文档进行修改

♻️ refactor: 代码重构（既不是新增功能，也不是修改 bug 的代码变动）

⚡ perf: 提高性能的代码修改

🧑‍💻 dx: 优化开发体验

🔨 workflow: 工作流变动

🏷️ types: 类型声明修改

🚧 wip: 工作正在进行中

✅ test: 测试用例添加及修改

🔨 build: 影响构建系统或外部依赖关系的更改

👷 ci: 更改 CI 配置文件和脚本

❓ chore: 其它不涉及源码以及测试的修改

⬆️ deps: 依赖项修改

🔖 release: 发布新版本

重大变更

重大更改是指可能破坏其他部分（包括用户）的更改，
导致开发人员或用户不得不做额外的工作。
进行重大更改的提交应在提交类型后附加一个 ! 符号。

作用域

<作用域> 是 可选 的，描述更改的影响范围。

对范围的描述没有严格的规定，但它应该是一个精确描述受影响区域的短语，并且应该 括在括号（ ( ) ）中。

使用 受影响函数的名称
（不是函数签名，可以是程序部分的抽象名称）通常是不错的选择。

主题

`<主题>`` 是变更内容的简短描述，
它应该是一个符合 以下规则 的 英文短句 ：

  • 不要 在开头使用大写字母。
  • 不要 以句号 ( . ) 结尾。
  • 使用 祈使句，现在时：
    “ change ”而不是“ changed ”或“ changes ”。
  • 不超过 50 个字符 。

正文

<正文> 是 可选 的，是对提交的 英文 详细描述。

当主题中的更改过于复杂而无法用一个英文短句描述时，
请使用 Markdown 列表以有组织的方式在正文中描述更改。

脚注

<footer> 是 可选 的，用于引用 issue 。

根据 GitHub Docs ，
有一些关键字可用于引用 issue ，甚至关闭它们。

我们使用关键字的一个子集：

  • Closes : 本次提交将关闭一个 issue。
    请 不要 使用此关键字，因为我们希望 GitHub 自动关闭问题。
  • Fixes : 本次提交解决了一个 issue。
    当提交最终解决了一个 issue（包括 bug 、功能请求等任何类型）时，
    使用此关键字引用该 issue ，而不是 Closes 。
  • Resolves : 本次提交 正在处理 一个issue。
    当提交正在解决一个 issue 时，
    特别是当提交不是解决该问题的唯一提交时，使用此关键字。

拉取请求 Pull Request

开发分支完成开发后，应创建一个 Pull Request ，
将该分支合并到dev分支中。

当 dev 分支处于稳定状态时，将创建一个标记为 [Release] 的拉取请求，
将其合并到 main 分支中。

main分支受到 严格保护 。
除了存储库的初始化外， 没有人 可以直接推送到主分支。

dev 分支受 保护 。
只有 仓库所有者或具有权限的人 才能直接推送至 dev 分支。

标题

拉取请求的标题应该是：
[<类型>] <简短描述> #<问题编号>

<类型> 是开发分支的类型。

<简短描述> 是问题的简短描述。

<问题编号> 是问题跟踪器中问题的编号，被该拉取请求用 # 引用。

一种例外情况是当合并 dev 分支到 main 分支时。
此时标题应为 [Release] <软件包名> <版本号> 。

描述

拉取请求的描述包含 主要修改或修复功能 。
如果您希望 审阅者 关注更改的某些部分，
请使用 markdown 清单 将其说明。

当新版本发布时，描述应该是该版本的发布说明。

一个简单的发布说明模板如下：

# CHANGELOG 更新日志

## Bug Fixes 问题修复

-  #<问题编号>

## Enhancements 功能优化

-  #<问题编号>

## Features 新功能

-  #<问题编号>

## <其他类别（双语描述）>

源分支和目标分支

源分支 目标分支
dev main
hotfix main
其他开发分支 dev

处理冲突

在 合并拉取请求之前 ，应先 解决冲突 。

有一种推荐的解决冲突的方法：

  • 将 目标分支 合并到 源分支 中。
  • 通过工具和解决冲突并提交。
  • 如果一切正常，将 源分支 合并到 目标分支 。

上述过程中，合并产生的 Git 提交消息使用 chore 分类，
并按照提交消息中的主题部分要求，将消息的第一个字母改为小写。

合并

审阅者应在合并之前 审阅拉取请求中的所有更改 。

合并拉取请求时，请始终使用 压缩并合并（ Squash and Merge ） 。

合并的 Git 提交消息主题应为 拉取请求的标题 。

合并的 Git 提交消息正文应为 拉取请求的更改 ，
由 GitHub 自动生成。

当合并标记为 [Release] 的拉取请求时，
合并的 Git 提交消息主题应为 [Release] <软件包名> <版本号> ，
正文应为该版本的发布说明。

Issue 模板

除以下部分外，Issue 的格式没有严格限制：

标题

Issue 的标题分为两部分：

[<类别>]: <描述> (<状态>)

类别为以下之一：

  • Bug: 有功能无法正常工作
  • Feature Request: 请求一项新的功能或特性
  • Enhancement: 请求增强现有功能
  • Documentation: 文档缺失或需要改进
  • Discussion: 讨论一些话题

<Catagory> 应包含在 [ ] 中。

<Description> 应该是问题的简短描述。
如果需要长篇描述，应该放在问题的正文中。

<Status> 是 可选的 ，它是问题的状态，只能由开发人员附加。
当修复合并到 dev 时，状态应附加为 Fixed 。
在修复合并到主分支后，问题将自动关闭。

负责人

处理 issue 的人。如果您不确定应该分配给谁，您可以将其留空。

标签

标签用于对问题分类。您可以向 issue 添加多个标签。

可用的标签大致有：

  • bug: 有功能无法正常工作
  • enhancement: 增强现有功能
  • documentation: 文档缺失或需要改进
  • discussion: 讨论一些话题
技术
规范
License:  CC BY 4.0