-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
035fc38
commit 6b99348
Showing
2 changed files
with
144 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,141 @@ | ||
# 贡献指南 | ||
|
||
- [简体中文](CONTRIBUTING.zh_CN.md) | ||
- [English](CONTRIBUTING.md) | ||
|
||
👍🎉 首先,感谢您抽出时间来贡献! 🎉👍 | ||
|
||
本项目遵循贡献者公约 [行为守则](CODE_OF_CONDUCT.md)。参与时,您需遵守此守则。如有不当行为,请报告至 | ||
kaiyu.shan@outlook.com。 | ||
|
||
以下是一组为 Centaur 做贡献的指南。这些仅是指导方针,而非规则,请根据实际情况判断,并随时在 Pull Request | ||
中提出对本文档的修改建议。 | ||
|
||
## 版本命名规范 | ||
|
||
确实有一些公认的版本命名规范,其中最著名的是**语义化版本控制**(Semantic Versioning,简称 | ||
SemVer)。语义化版本控制为版本号的格式和使用提供了一套标准化规则,旨在帮助开发者理解版本变更的性质和影响。 | ||
|
||
### 语义化版本控制 | ||
|
||
**语义化版本控制**规范定义了以下版本号格式: | ||
|
||
``` | ||
MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD] | ||
``` | ||
|
||
- **MAJOR**:主版本号。当你做了不兼容的 API 修改时,增加此版本号。 | ||
- **MINOR**:次版本号。当你在保持向后兼容的情况下添加功能时,增加此版本号。 | ||
- **PATCH**:修订号。当你做了向后兼容的问题修正时,增加此版本号。 | ||
- **PRERELEASE**:可选的预发布标识,标识未完成或实验性版本。 | ||
- **BUILD**:可选的构建元数据,提供有关构建的附加信息。 | ||
|
||
**示例**: | ||
|
||
- `1.0.0`:初始发布版本。 | ||
- `1.1.0`:添加了向后兼容的功能。 | ||
- `1.0.1`:做了向后兼容的修正。 | ||
- `2.0.0`:进行了不兼容的 API 修改。 | ||
- `1.0.0-alpha`:预发布版本。 | ||
- `1.0.0+build5678`:包含构建元数据的版本。 | ||
|
||
在语义化版本控制(SemVer)中,如果同时进行功能添加和修复,版本号的更新应根据更改的类型来确定。以下是处理这种情况的原则和建议: | ||
|
||
### 更新版本号的原则 | ||
|
||
1. **优先级**: | ||
- 如果有多种类型的更改(例如功能添加和修复),版本号的更新应基于更改中最重要的部分。 | ||
- 通常,功能添加的优先级高于修复,因此如果同时进行了功能添加和修复,版本号的更新主要应基于功能添加。 | ||
|
||
2. **修订号(PATCH)**: | ||
- 如果仅进行了修复,且没有添加新功能或进行不兼容的更改,则应更新修订号(PATCH)。 | ||
|
||
3. **次版本号(MINOR)**: | ||
- 如果进行了功能添加并保持向后兼容,但没有进行不兼容的更改,则应更新次版本号(MINOR)。 | ||
|
||
4. **主版本号(MAJOR)**: | ||
- 如果进行了不兼容的更改,无论是功能添加还是修复,都应更新主版本号(MAJOR)。 | ||
|
||
### 实际示例 | ||
|
||
- **功能添加和修复**: | ||
- **功能添加**(保持向后兼容):更新次版本号。 | ||
- **修复**(向后兼容):可以增加修订号,但在功能添加的情况下,次版本号的增加已经涵盖了修复内容。 | ||
- **示例**:假设当前版本为 `1.0.0`。如果添加了新功能并修复了错误,应将版本号更新为 `1.1.0` 而不是 | ||
`1.0.1`。这是因为功能添加通常比修复更为重要,而 `1.1.0` 已经隐含了修复内容。 | ||
|
||
- **同时进行不兼容的更改**: | ||
- 如果同时进行了不兼容的 API 更改,则应更新主版本号(MAJOR)。 | ||
- **示例**:如果当前版本为 `1.0.0`,并进行了不兼容的 API 更改、功能添加和修复,则版本号应更新为 | ||
`2.0.0`。 | ||
|
||
### 综合考虑 | ||
|
||
如果版本更新包含多种类型的更改,通常的做法是根据主要更改类型来确定版本号的更新。功能添加通常会推动次版本号的增加,而不兼容的更改会推动主版本号的增加。 | ||
|
||
确保所有重要的更改都准确地反映在版本号中,并在发布说明中记录具体的更改,以帮助用户理解版本更新的性质和影响。 | ||
|
||
**预发布标识**: | ||
|
||
在语义化版本控制中,预发布标识(Pre-release | ||
label)用于标识版本的特定预发布状态。这些版本通常仍在测试阶段或尚未完成。预发布标识帮助用户区分不同阶段的版本,并提供附加信息。 | ||
|
||
### 常见的预发布标识 | ||
|
||
1. **alpha**: | ||
- **描述**:表示早期开发版本,通常包含未完成的功能,可能不稳定,主要用于内部测试或早期反馈。 | ||
- **示例**:`1.0.0-alpha` | ||
|
||
2. **beta**: | ||
- **描述**:表示基本功能完成但可能仍有问题的版本,通常用于广泛测试,可能包含一些已知问题或缺陷。 | ||
- **示例**:`1.0.0-beta` | ||
|
||
3. **rc**(Release Candidate,发布候选版本): | ||
- **描述**:表示发布候选版本,通常是接近正式发布的版本,用于最后测试。如果未发现重大问题,此版本可能成为正式稳定版本。 | ||
- **示例**:`1.0.0-rc1` | ||
|
||
4. **snapshot**: | ||
- **描述**:表示正在进行开发的版本,通常是频繁更新的版本,可能在开发的各个阶段发布以测试最新的更改。 | ||
- **示例**:`1.0.0-snapshot` | ||
|
||
5. **dev**(Development,开发版本): | ||
- **描述**:表示正在开发中的版本,通常用于标识开发中的版本,可能包含不稳定的功能或未完成的工作。 | ||
- **示例**:`1.0.0-dev` | ||
|
||
6. **test**: | ||
- **描述**:表示测试阶段的版本,用于验证软件的特定功能或进行集成测试。 | ||
- **示例**:`1.0.0-test` | ||
|
||
7. **pre**(Pre-release,预发布): | ||
- **描述**:一个通用的预发布标识,表示版本在正式发布前,通常用于各种预发布阶段。 | ||
- **示例**:`1.0.0-pre` | ||
|
||
### 预发布标识的使用 | ||
|
||
- 预发布标识应放在版本号之后,以连字符 `-` 作为前缀,例如 `1.0.0-alpha`。 | ||
- 可以包含数字和字母以标识不同的预发布版本。例如,`1.0.0-beta2` 表示第二个 beta 版本。 | ||
- 标记为预发布的版本不会影响版本排序;在排序时,预发布版本会被认为早于正式版本。 | ||
|
||
**示例**: | ||
|
||
- `1.0.0-alpha` < `1.0.0-beta` < `1.0.0-rc1` < `1.0.0` | ||
|
||
使用预发布标识可以帮助开发团队和用户识别发布版本的开发阶段,并确定其是否适合生产环境。确保在发布说明中详细记录预发布的功能和已知问题,以帮助用户做出选择。 | ||
|
||
### 语义化版本控制的主要原则 | ||
|
||
1. **版本号的递增**:当发生不兼容的 API 更改时,增加主版本号;当添加了新功能且保持向后兼容时,增加次版本号;当进行了向后兼容的修复时,增加修订号。 | ||
2. **预发布和构建元数据**:预发布标识和构建元数据不会影响版本号的排序,仅用于提供附加信息。 | ||
|
||
### 其他版本控制规范 | ||
|
||
尽管语义化版本控制是最广泛接受的标准,但仍存在其他规范和变体: | ||
|
||
1. **日期版本控制**:使用日期作为版本号的一部分,如 `2024.09.04`。这种方法适用于发布频率高的项目。 | ||
2. **Git Hash**:一些项目会使用 Git 提交哈希作为版本号的一部分,特别是在开发或持续集成期间。 | ||
|
||
### 官方参考 | ||
|
||
- **语义化版本控制官方规范**:[Semantic Versioning 2.0.0](https://semver.org/) | ||
|
||
这些规范帮助开发者理解版本变更的影响,并确保项目版本清晰一致。根据项目需求选择合适的规范,并确保团队对版本命名规则达成一致。 |