Skip to content

Commit

Permalink
docs(centaur): 贡献指南增加中文版本
Browse files Browse the repository at this point in the history
  • Loading branch information
conifercone committed Sep 4, 2024
1 parent 035fc38 commit 6b99348
Show file tree
Hide file tree
Showing 2 changed files with 144 additions and 0 deletions.
3 changes: 3 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
# Contributing to Centaur

- [简体中文](CONTRIBUTING.zh_CN.md)
- [English](CONTRIBUTING.md)

👍🎉 First off, thanks for taking the time to contribute! 🎉👍

This project adheres to the Contributor Covenant [code of conduct](CODE_OF_CONDUCT.md).
Expand Down
141 changes: 141 additions & 0 deletions CONTRIBUTING.zh_CN.md
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/)

这些规范帮助开发者理解版本变更的影响,并确保项目版本清晰一致。根据项目需求选择合适的规范,并确保团队对版本命名规则达成一致。

0 comments on commit 6b99348

Please sign in to comment.