From a93e03f425392cf419604c5d5dfe8547132ddd2e Mon Sep 17 00:00:00 2001 From: 7Wate Date: Mon, 26 Jun 2023 17:37:53 +0800 Subject: [PATCH] =?UTF-8?q?Git=EF=BC=9A=E5=8D=8F=E4=BD=9C=E8=A7=84?= =?UTF-8?q?=E8=8C=83=202.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../Git/高级/协作规范/交流反馈（Issue）.md | 50 ++++-- .../Git/高级/协作规范/关于（Readme）.md | 148 +++++++++++++----- .../Git/高级/协作规范/分支（Branch）.md | 72 +++------ .../Git/高级/协作规范/开源协议（License）.md | 19 ++- .../Git/高级/协作规范/日志（Commit）.md | 65 +++++--- .../Git/高级/协作规范/注释（Comments）.md | 35 ++--- .../Git/高级/协作规范/版本（Tag）.md | 96 ++---------- .../协作规范/贡献者协议（Contributing）.md | 103 ++++++++---- wiki/getting-started/文档/文档内容.md | 12 +- 9 files changed, 322 insertions(+), 278 deletions(-) diff --git a/wiki/getting-started/Git/高级/协作规范/交流反馈（Issue）.md b/wiki/getting-started/Git/高级/协作规范/交流反馈（Issue）.md index be22129e..939e64ea 100644 --- a/wiki/getting-started/Git/高级/协作规范/交流反馈（Issue）.md +++ b/wiki/getting-started/Git/高级/协作规范/交流反馈（Issue）.md @@ -1,16 +1,27 @@ --- -id: 交流反馈（Issue） title: 交流反馈（Issue） -data: 2022年6月15日 +description: Git 协作交流反馈（Issue） +keywords: +- Git +- 协作规范 +- 交流反馈 +tags: +- 协作规范 sidebar_position: 5 +author: 7Wate +date: 2023-06-26 --- -## 规范 -- 文件命名：ISSUE.md +文件命名：**ISSUE.md**。 +## 新需求（Pull Request） -### 新需求（Pull Request） +规范：使用`Pr:title`来命名。``表示需求涉及的模块或功能，`title`则表示具体需求的主题。 + +示例：`Pr(auth):role-based authorization` + +提交新需求时，请遵循以下格式： 规范：`Pr:title` @@ -20,25 +31,28 @@ sidebar_position: 5 ## 背景 - 描述你希望解决的问题 -- 附上相关的 issue 或社区帖 +- 如果相关的 issue 或社区帖子已存在，请附上链接 ## 思路 -描述解决思路，可以包含 API 设计和伪代码等 +描述解决思路，可以包含 API 设计和伪代码等。 ## 实现 -附上对应的 Pull Request 地址。 +附上对应的 Pull Request 地址。如果还未实现，可以描述你打算如何实现此需求。 + ``` -### 反馈缺陷（Bug） +## 反馈缺陷（Bug） -请务必先阅读**提问的智慧！** +在提交Bug前，请务必先阅读**提问的智慧！** -规范：`Bug:title` +规范：使用`Bug:title`来命名。``表示Bug涉及的模块或功能，`title`则表示Bug的主要问题。 示例：`Bug(login):Admin password cannot be reset` +提交Bug反馈时，请遵循以下格式： + ```markdown ## 运行环境 @@ -55,17 +69,20 @@ sidebar_position: 5 ## 报错信息 -- 报错信息、日志等 +- 附上具体的报错信息、日志等。如果可能，截图也会非常有用。 + ``` -### 答疑交流（Usage） +## 答疑交流（Usage） -一般来说，更推荐使用社区自助交流方式。 +一般来说，我们更推荐使用社区自助交流方式。 -规范：`Usage:title` +规范：使用`Usage:title`来命名。``表示问题涉及的模块或功能，`title`则表示问题的主要内容。 示例：`Usage(update):1.2.3 version update failed` +提交问题或请求帮助时，请遵循以下格式： + ```markdown ## 运行环境 @@ -74,5 +91,6 @@ sidebar_position: 5 ## 报错信息 -- 报错信息、日志等 +- 提供详细的报错信息、日志等。截图，如果可能，也是非常有用的。 + ``` diff --git a/wiki/getting-started/Git/高级/协作规范/关于（Readme）.md b/wiki/getting-started/Git/高级/协作规范/关于（Readme）.md index 2d8c25c0..30d72301 100644 --- a/wiki/getting-started/Git/高级/协作规范/关于（Readme）.md +++ b/wiki/getting-started/Git/高级/协作规范/关于（Readme）.md @@ -1,69 +1,133 @@ --- -id: 关于（Readme） title: 关于（Readme） -data: 2022年6月15日 +description: Git 协作关于（Readme） +keywords: +- Git +- 协作规范 +- README +tags: +- 协作规范 sidebar_position: 4 +author: 7Wate +date: 2023-06-26 --- -## 规范 -- 文件命名：README.md、README_EN.md，根据项目受众群体标定关于文档的默认语言。 -- 徽章：[https://shields.io/](https://shields.io/) +README 文件的命名应以项目的受众群体为依据。命名 README.md、README_EN.md、README_ZH.md。 -### 中文模板 +## 中文模板 ```markdown -## 项目 +# 项目名称 - ### 徽章 - ### 简介 - ### 演示 - ### 原理图 / 流程图 - -## 用法 +## 徽章 - ### 安装 - ### 文档 - ### F&Q +[![Badge](https://img.shields.io/badge/Badge-Text-blue)](链接) -## 路线 +## 简介 - ### 开发路线 - ### 更新历史（可单独文件） +在这部分，提供对你的项目的简短描述，包括其功能，目标和主要特性。 -## 贡献 - -## 致谢 +## 演示 -## 协议 +如果可能的话，提供一个项目演示的链接或者是屏幕录像。这可以让用户直观地了解项目的功能和使用方式。 +## 原理图 / 流程图 + +如果项目的工作原理复杂或者涉及到一些特定的流程，可以在这里提供一个原理图或者流程图来帮助理解。 + +# 用法 + +## 安装 + +提供详细的安装指南，包括所有必要的步骤和要求。 + +## 文档 + +提供关于如何使用项目的详细信息，或者链接到详细的文档。 + +## FAQ + +列出一些常见的问题和答案，以帮助用户解决可能遇到的问题。 + +# 路线 + +## 开发路线 + +描述项目的未来发展计划，包括新功能和改进。 + +## 更新历史 + +提供一个项目的更新历史，包括版本号、更新日期以及主要的修改。 + +# 贡献 + +说明如何为项目做出贡献，包括代码、文档或者报告问题。 + +# 致谢 + +向为项目提供帮助的人或者组织表示感谢。 + +# 协议 + +列出项目的许可协议，或者提供一个链接到全文。 ``` -### 英文模板 +## 英文模板 ```markdown -## Project +# Project Name - ### Badges - ### Introduction - ### Demo - ### Schematic / Flowchart - -## Usage +## Badges - ### Install - ### Documentation - ### F&Q +[![Badge](https://img.shields.io/badge/Badge-Text-blue)](Link) -## Map +## Introduction - ### Development map - ### Update history (can be a separate file) +In this section, provide a brief description of your project, including its functions, goals, and main features. -## Contribute - -## Thanks +## Demo + +If possible, provide a link to a project demo or a screencast. This can give users a direct understanding of the project's functionality and usage. + +## Schematic / Flowchart + +If the working principle of the project is complex or involves specific processes, provide a schematic or flowchart to aid understanding here. + +# Usage + +## Install + +Provide detailed installation guides, including all necessary steps and requirements. + +## Documentation + +Provide detailed information on how to use the project, or link to detailed documentation. + +## FAQ + +List some common questions and answers to help users solve possible problems. + +# Map + +## Development map + +Describe the future development plan of the project, including new features and improvements. + +## Update history + +Provide a history of project updates, including version numbers, update dates, and major modifications. + +# Contribute + +Explain how to contribute to the project, including code, documentation, or reporting issues. + +# Thanks + +Express gratitude to individuals or organizations that have provided help for the project. + +# License + +List the project's license, or provide a link to the full text. -## License ``` - diff --git a/wiki/getting-started/Git/高级/协作规范/分支（Branch）.md b/wiki/getting-started/Git/高级/协作规范/分支（Branch）.md index 0b518450..31c6c7d3 100644 --- a/wiki/getting-started/Git/高级/协作规范/分支（Branch）.md +++ b/wiki/getting-started/Git/高级/协作规范/分支（Branch）.md @@ -1,42 +1,44 @@ --- -id: 分支（Branch） title: 分支（Branch） +description: 分支 +keywords: +- Git +- 分支 +- 协作规范 +tags: +- 协作规范 sidebar_position: 1 -data: 2022年6月15日 +author: 7Wate +date: 2023-06-26 --- -## 规范 ![git-flow](https://static.7wate.com/img/2022/10/09/a24754d19f904.png) -主分支命名：`master `、`main` +| 分支类型 | 命名规则 | 备注 | +| ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| 主分支 | `main` | | +| 开发分支 | `develop` | | +| 功能分支 | 除 `master`、`main`、`develop`、`release-*`、`hotfix-*` 以外的任何名字 | 避免使用 `master`、`main`、`develop`、`release-*`、`hotfix-*` | +| 预发布分支 | `release-*` | 名称中的 `*` 表示版本号或其他标识 | +| 热修复分支 | `hotfix-*` | 名称中的 `*` 表示版本号或其他标识 | -开发分支命名：`develop` - -功能分支命名：除 `master`、`main`、`develop`、`release-*`、`hotfix-*` 以外的任何名字 - -预发布分支命名：`release-*` - -热修复分支命名：`hotfix-*` - -防止产生歧义，**建议禁止简拼。** +**为了防止产生歧义，我们建议避免使用简拼命名。** ## 主要分支 -在中央仓库中有两个生命期无限长的主要分支： +中央仓库中存在两个生命期无限长的主要分支： -- Master（主分支） -- Developer（开发分支） +- Main（主分支） +- Develop（开发分支） -默认主要分支 `origin/master` 的 `HEAD` 所指向的源码总是处于**可发布**的状态。 +主分支 `origin/main` 的 `HEAD` 指向的源码总是处于可发布的状态。另一方面，开发分支 `origin/develop` 的 `HEAD` 指向的源码应包含为下次版本发布准备的最近的一次提交。 -默认主要分支 `origin/develop` 的 `HEAD` 所指向的源码总是处于为下次发版所做的最近的一次修改提交的状态。 - -当 `develop` 分支上的代码达到了一个稳定的点并且准备进行发版时，在该分支上所做的所有修改都应该被合并回 `master` 分支，并且打一个版本号标签（`tag`）。 +当 `develop` 分支上的代码达到一个稳定点，并且准备进行发版时，所有在该分支上的修改都应该合并回 `main` 分支，并且打一个版本号标签（`tag`）。 ## 辅助分支 -伴随着主要分支 `master` 和 `develop` ，我们的开发模式还用了一些辅助分支来协助团队成员间的平行开发，使对功能的追踪变得轻便，并且协助产品的发布，以及进行线上版本bug的快速修复。 +为了协助平行开发，简化功能追踪，协助产品发布和快速修复线上版本的bug，我们采用了功能分支、预发布分支和热修复分支。 - Feature branches (功能分支) - Release branches (预发布分支) @@ -44,34 +46,12 @@ data: 2022年6月15日 ### 功能分支 -- 分支：创建自：`develop`；必须合并回：`develop`。 - -- 分支命名：除 `master`、`develop`、`release-*`、`hotfix-*` 以外的任何名字 - -功能分支通常**只存在于开发者的本地仓库中**，并不包含在远程库 `origin` 中。 +功能分支是从 `develop` 创建，必须合并回 `develop`。这些分支主要存在于开发者的本地仓库，不在远程仓库 `origin` 中。 ### 预发布分支 -- 分支：创建自：`develop`；必须合并回：`develop` 和 `master`。 - -- 分支命名：`release-*`。 - -预发布分支主要用来协助一个新版本发布的准备工作。 - -它允许对预发布版本做最后的打点，例如做一些较小的 **bug 修复**并且准备一些发版的数据(版本号和编译数据等)。**最后**，在该预发布分支上所做的修改要合并回 `develop` 分支，这样以后的版本就也包含了在该预发布分支上所做的bug修复。 - -正式发布后就可以删掉该预发布分支了。 +预发布分支从 `develop` 创建，必须合并回 `develop` 和 `main`。这些分支用于准备新版本的发布，包括进行小的bug修复和准备发布数据。发布后，预发布分支可以删除。 ### 热修复分支 -- 分支：创建自：`master`；必须合并回：`develop` 和 `master`； - -- 分支命名：`hotfix-*`。 - -热修复分支也是用来协助新版本发布的，在这点上和预发布分支相似，但该分支不是必须存在的。 - -该分支的创建主要是用来及时应对线上版本所出现的意外情况。当线上版本出现一个需要立刻修复的严重bug时，我们可以从 `master` 分支上标记为当前线上版本号的`tag`处切出一个热修复分支。 - -当完成了紧急 bug 的修复时，要将该热修复分支合并回 `master` 分支，**并且同时也要将其合并回 `develop` 分支**，以确保对该 bug 的修复也同时包含在下一次发版中。**如果此时同时存在一个预发布分支，那么要把该热修复分支合并回该预发布分支，而不是 `develop` 分支**。 - -最后就可以删掉该热修复分支了。 +热修复分支从 `main` 创建，必须合并回 `develop` 和 `main`。这些分支用于修复线上版本的严重 bug。修复完成后，热修复分支可以删除。如果当前存在预发布分支，热修复分支应该合并到预发布分支，而不是开发分支。 diff --git a/wiki/getting-started/Git/高级/协作规范/开源协议（License）.md b/wiki/getting-started/Git/高级/协作规范/开源协议（License）.md index 0d388f7f..ab4d7d04 100644 --- a/wiki/getting-started/Git/高级/协作规范/开源协议（License）.md +++ b/wiki/getting-started/Git/高级/协作规范/开源协议（License）.md @@ -1,14 +1,19 @@ --- -id: 开源协议（License） title: 开源协议（License） -data: 2022年6月15日 +description: Git 开源协议（License） +keywords: +- Git +- 开源协议 +- 协作规范 +tags: +- 协作规范 sidebar_position: 7 +author: 7Wate +date: 2023-06-26 --- -## 规范 +文件命名：LICENSE + +许可证向导：[https://kaiyuanshe.cn/license-tool/](https://kaiyuanshe.cn/license-tool/) ![快速选择开源协议](https://static.7wate.com/img/2020/07/02/fe11588b073bf.png) - -- 文件命名：LICENSE -- 许可证向导：https://kaiyuanshe.cn/license-tool/ - diff --git a/wiki/getting-started/Git/高级/协作规范/日志（Commit）.md b/wiki/getting-started/Git/高级/协作规范/日志（Commit）.md index 3d80153b..23375ad6 100644 --- a/wiki/getting-started/Git/高级/协作规范/日志（Commit）.md +++ b/wiki/getting-started/Git/高级/协作规范/日志（Commit）.md @@ -1,19 +1,22 @@ --- -id: 日志（Commit） title: 日志（Commit） +description: Git 协作日志 +keywords: +- Git +- 协作 +- 日志 +tags: +- Git sidebar_position: 2 -data: 2022年6月15日 +author: 7Wate +date: 2023-06-26 --- -## 规范 +对于项目，日志内容应使用 **ASCII** 字符、中文或 emoji，以实现**最大化的兼容性**，方便进行兼容处理。 -项目根据实际情况，日志内容使用 **ASCII** 字符、中文或 emoji，尽量要求**最大化兼容**，便于兼容处理。 +commit 包含三个部分：**Header**、**Body**、**Footer**。 -commit 包括三个部分：**Header**、**Body**、**Footer**。 - -commit 格式如下： - -```text +```markdown ([scope]): [body] @@ -23,7 +26,7 @@ commit 格式如下： 示例： -```text +```markdown feature(auth): increase length of new API key the length is increased from 24 to 32 for new API keys @@ -31,27 +34,37 @@ the length is increased from 24 to 32 for new API keys close #12 ``` -### 头部（Header） +## 头部（Header） -标题部分只有一行，包括三个字段：类型、说明、标题。 +头部只有一行，包含三个字段：类型、范围和主题。 -![commit-tag.png](https://static.7wate.com/img/2021/08/24/a26a82a44ce2e.png) +| 全拼 | 简拼 | 描述 | +| ---------------------- | -------- | -------------------------------------------------------- | +| feature | feat | 新增特性 | +| fix | fix | 修复 bug | +| documents | docs | 文档变动 | +| style | style | 代码格式（不影响功能，例如空格、分号等格式修正） | +| refactor | refactor | 代码重构 | +| performance | perf | 改善性能 | +| test | test | 测试 | +| build | build | 影响构建系统或外部依赖的更改（例如：gulp、npm、webpack） | +| continuous integration | ci | 更改了 CI 配置文件和脚本 | +| chore | chore | 对构建过程或辅助工具和库的更改（不影响源文件、测试用例） | +| revert | revert | 撤销上一次的 commit | -- 破坏兼容性的改动，影响到依赖本项目的其它系统，请在类型后面加上**半角感叹号**「**!**」。 -- 标题务必不超过 **72** 个字符，务必精炼易懂。如无法限制在 **72** 个字符内，请拆分提交。 -- 描写部分**小写字母开头**、专有名词首字母大写、缩略语大写、结尾不用句号。 +- 对于破坏兼容性的更改，即会影响到依赖本项目的其他系统的更改，请在类型后面加上**半角感叹号**「**!**」。 +- 主题务必不超过 **72** 个字符，且必须简洁明了。如果无法限制在 **72** 个字符内，请拆分提交。 +- 主题部分应**以小写字母开头**，专有名词首字母大写，缩略语大写，并且结尾不用句号。 -### 主体（Body） +## 主体（Body） -标题与正文间隔一个空行。 +主题与正文之间应有一个空行。 -如果内容简单，请按照标题格式。超过一行，按照常规的段落格式。 +如果内容简单，可以按照主题格式撰写。如果超过一行，应按照常规的段落格式。 -**首字母大写，正确使用标点。可以多行、多段、每行不超过 72 个字符、行尾不出现空格、段落用空行隔开。** +**首字母应大写，正确使用标点。可以有多行或多段，但每行不超过 72 个字符，行尾不出现空格，段落之间应用空行隔开。** -示例 - -```text +```markdown feature!(api): limit array length to 256 elements BREAKING: Array length limit is added to further limit request size. A @@ -59,6 +72,8 @@ small number of existing apps may receive HTTP 413 "Payload too Large" error. ``` -### 脚注（Footer） +## 脚注（Footer） -正文与脚注间隔一个空行。 +正文与脚注之间应有一个空行。 + +脚注主要用于记录不兼容的更改和关闭问题的操作。对于不兼容的更改，需要在脚注中进行描述，同时还需要在主体部分进行详细描述。如果关闭的问题是在追踪系统（如 GitHub）中的问题，需要在脚注中使用 "Close #issue" 格式进行描述。 diff --git a/wiki/getting-started/Git/高级/协作规范/注释（Comments）.md b/wiki/getting-started/Git/高级/协作规范/注释（Comments）.md index fc6861d9..aff2348b 100644 --- a/wiki/getting-started/Git/高级/协作规范/注释（Comments）.md +++ b/wiki/getting-started/Git/高级/协作规范/注释（Comments）.md @@ -1,20 +1,23 @@ --- -id: 注释（Comments） title: 注释（Comments） +description: Git 协作注释 +keywords: +- Git +- 协作 +- 注释 +tags: +- Git sidebar_position: 1.5 -data: 2022年7月11日 +author: 7Wate +date: 2023-06-26 --- -## 规范 -**代码**就是**最好的注释**，尽量使用**英文注释**，坚决**不滥用**注释。**不需要**标明**作者、时间、改动记录**，请把这些放在 **Git** 对应**提交日志**中！ -### 代码注释 +**代码**应视为**最好的注释**，因此应尽量使用**英文注释**，并坚决**避免滥用**注释。不必在代码中标明**作者、时间、或改动记录**，这些信息应放在 **Git** 的**提交日志**中！ -#### 行注释 +## 行注释 -行注释位于该**行代码前**，建议切勿代码后注释。 - -规范： +行注释应放在相应代码行**之前**，而不是代码行之后。 ```javascript // 注释文字 @@ -28,11 +31,9 @@ data: 2022年7月11日 const portable = bootstrapNode.configurePortable(product); ``` -#### 关键字注释 +## 关键字注释 -注释块**尾部**，关键字前添加 `@` 符号。 - -规范： +在注释块的**尾部**，关键字前添加 `@` 符号。 ```javascript /* @@ -57,11 +58,9 @@ function mkdirp(dir) { } ``` -### 版权注释 +## 版权注释 -版权注释位于**代码文件首行**。 - -规范： +版权注释应位于**代码文件首行**。 ```javascript /*---------------- @@ -72,7 +71,7 @@ function mkdirp(dir) { 代码··· ``` -上下分割线要求是描述文字长度 1.1 倍，`/* */` 不令其一行，描述文字前保持 1 个空格。 +上下分割线的长度应为描述文字长度的 1.1 倍。`/* */`不应与注释内容放在同一行，且描述文字前应保持 1 个空格。 示例： diff --git a/wiki/getting-started/Git/高级/协作规范/版本（Tag）.md b/wiki/getting-started/Git/高级/协作规范/版本（Tag）.md index 93372966..3bc8c6af 100644 --- a/wiki/getting-started/Git/高级/协作规范/版本（Tag）.md +++ b/wiki/getting-started/Git/高级/协作规范/版本（Tag）.md @@ -1,96 +1,24 @@ --- -id: 版本（Tag） title: 版本（Tag） -data: 2022年6月15日 +description: Git 协作版本（Tag） +keywords: +- Git +- 协作规范 +- 版本 +tags: +- 协作规范 sidebar_position: 3 +author: 7Wate +date: 2023-06-26 --- -## 规范 ![语义化版本.png](https://static.7wate.com/img/2021/08/24/ad4999467e192.png) 首发版本以 **0.1.0** 开始，版本格式：主版本号.次版本号.修订号，递增规则如下： 1. 主版本号：当你做了不兼容的 API 修改， -2. 次版本号：当你做了向下兼容的**功能性新增**， -3. 修订号：当你做了向下兼容的**问题修正**。 +2. 次版本号：当你做了向下兼容的功能性新增， +3. 修订号：当你做了向下兼容的问题修正。 -## 语义化版本控制 - -### 简介 - -在软件管理的领域里存在着被称作“依赖地狱”的死亡之谷，系统规模越大，加入的包越多，你就越有可能在未来的某一天发现自己已深陷绝望之中。 - -在依赖高的系统中发布新版本包可能很快会成为噩梦。如果依赖关系过高，可能面临版本控制被锁死的风险（必须对每一个依赖包改版才能完成某次升级）。而如果依赖关系过于松散，又将无法避免版本的混乱（假设兼容于未来的多个版本已超出了合理数量）。当你项目的进展因为版本依赖被锁死或版本混乱变得不够简便和可靠，就意味着你正处于依赖地狱之中。 - -作为这个问题的解决方案之一，我提议用一组简单的规则及条件来约束版本号的配置和增长。这些规则是根据（但不局限于）已经被各种封闭、开放源码软件所广泛使用的惯例所设计。为了让这套理论运作，你必须先有定义好的公共 API。这可以透过文件定义或代码强制要求来实现。无论如何，这套 API 的清楚明了是十分重要的。一旦你定义了公共 API，你就可以透过修改相应的版本号来向大家说明你的修改。考虑使用这样的版本号格式：X.Y.Z（主版本号.次版本号.修订号）修复问题但不影响 API 时，递增修订号；API 保持向下兼容的新增及修改时，递增次版本号；进行不向下兼容的修改时，递增主版本号。 - -我称这套系统为“语义化的版本控制”，在这套约定下，版本号及其更新方式包含了相邻版本间的底层代码和修改内容的信息。 - -### 语义化版本控制规范（SemVer） - -以下关键词 MUST、MUST NOT、REQUIRED、SHALL、SHALL NOT、SHOULD、SHOULD NOT、 RECOMMENDED、MAY、OPTIONAL 依照 RFC 2119 的叙述解读。 - -1. 使用语义化版本控制的软件必须（MUST）定义公共 API。该 API 可以在代码中被定义或出现于严谨的文件内。无论何种形式都应该力求精确且完整。 -2. 标准的版本号必须（MUST）采用 X.Y.Z 的格式，其中 X、Y 和 Z 为非负的整数，且禁止（MUST NOT）在数字前方补零。X 是主版本号、Y 是次版本号、而 Z 为修订号。每个元素必须（MUST）以数值来递增。例如：1.9.1 -> 1.10.0 -> 1.11.0。 -3. 标记版本号的软件发行后，禁止（MUST NOT）改变该版本软件的内容。任何修改都必须（MUST）以新版本发行。 -4. 主版本号为零（0.y.z）的软件处于开发初始阶段，一切都可能随时被改变。这样的公共 API 不应该被视为稳定版。 -5. 1.0.0 的版本号用于界定公共 API 的形成。这一版本之后所有的版本号更新都基于公共 API 及其修改内容。 -6. 修订号 Z（x.y.Z `|` x > 0）必须（MUST）在只做了向下兼容的修正时才递增。这里的修正指的是针对不正确结果而进行的内部修改。 -7. 次版本号 Y（x.Y.z `|` x > 0）必须（MUST）在有向下兼容的新功能出现时递增。在任何公共 API 的功能被标记为弃用时也必须（MUST）递增。也可以（MAY）在内部程序有大量新功能或改进被加入时递增，其中可以（MAY）包括修订级别的改变。每当次版本号递增时，修订号必须（MUST）归零。 -8. 主版本号 X（X.y.z `|` X > 0）必须（MUST）在有任何不兼容的修改被加入公共 API 时递增。其中可以（MAY）包括次版本号及修订级别的改变。每当主版本号递增时，次版本号和修订号必须（MUST）归零。 -9. 先行版本号可以（MAY）被标注在修订版之后，先加上一个连接号再加上一连串以句点分隔的标识符来修饰。标识符必须（MUST）由 ASCII 字母数字和连接号 [0-9A-Za-z-] 组成，且禁止（MUST NOT）留白。数字型的标识符禁止（MUST NOT）在前方补零。先行版的优先级低于相关联的标准版本。被标上先行版本号则表示这个版本并非稳定而且可能无法满足预期的兼容性需求。范例：1.0.0-alpha、1.0.0-alpha.1、1.0.0-0.3.7、1.0.0-x.7.z.92。 -10. 版本编译信息可以（MAY）被标注在修订版或先行版本号之后，先加上一个加号再加上一连串以句点分隔的标识符来修饰。标识符必须（MUST）由 ASCII 字母数字和连接号 [0-9A-Za-z-] 组成，且禁止（MUST NOT）留白。当判断版本的优先层级时，版本编译信息可（SHOULD）被忽略。因此当两个版本只有在版本编译信息有差别时，属于相同的优先层级。范例：1.0.0-alpha+001、1.0.0+20130313144700、1.0.0-beta+exp.sha.5114f85。 -11. 版本的优先层级指的是不同版本在排序时如何比较。判断优先层级时，必须（MUST）把版本依序拆分为主版本号、次版本号、修订号及先行版本号后进行比较（版本编译信息不在这份比较的列表中）。由左到右依序比较每个标识符，第一个差异值用来决定优先层级：主版本号、次版本号及修订号以数值比较，例如：1.0.0 < 2.0.0 < 2.1.0 < 2.1.1。当主版本号、次版本号及修订号都相同时，改以优先层级比较低的先行版本号决定。例如：1.0.0-alpha < 1.0.0。有相同主版本号、次版本号及修订号的两个先行版本号，其优先层级必须（MUST）透过由左到右的每个被句点分隔的标识符来比较，直到找到一个差异值后决定：只有数字的标识符以数值高低比较，有字母或连接号时则逐字以 ASCII 的排序来比较。数字的标识符比非数字的标识符优先层级低。若开头的标识符都相同时，栏位比较多的先行版本号优先层级比较高。范例：1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0。 - -### 为什么要使用语义化的版本控制？ - -这并不是一个新的或者革命性的想法。实际上，你可能已经在做一些近似的事情了。问题在于只是“近似”还不够。如果没有某个正式的规范可循，版本号对于依赖的管理并无实质意义。将上述的想法命名并给予清楚的定义，让你对软件使用者传达意向变得容易。一旦这些意向变得清楚，弹性（但又不会太弹性）的依赖规范就能达成。 - -举个简单的例子就可以展示语义化的版本控制如何让依赖地狱成为过去。假设有个名为“救火车”的函数库，它需要另一个名为“梯子”并已经有使用语义化版本控制的包。当救火车创建时，梯子的版本号为 3.1.0。因为救火车使用了一些版本 3.1.0 所新增的功能，你可以放心地指定依赖于梯子的版本号大于等于 3.1.0 但小于 4.0.0。这样，当梯子版本 3.1.1 和 3.2.0 发布时，你可以将直接它们纳入你的包管理系统，因为它们能与原有依赖的软件兼容。 - -作为一位负责任的开发者，你理当确保每次包升级的运作与版本号的表述一致。现实世界是复杂的，我们除了提高警觉外能做的不多。你所能做的就是让语义化的版本控制为你提供一个健全的方式来发行以及升级包，而无需推出新的依赖包，节省你的时间及烦恼。 - -如果你对此认同，希望立即开始使用语义化版本控制，你只需声明你的函数库正在使用它并遵循这些规则就可以了。请在你的 README 文件中保留此页链接，让别人也知道这些规则并从中受益。 - -### FAQ - -#### 在 0.y.z 初始开发阶段，我该如何进行版本控制？ - -最简单的做法是以 0.1.0 作为你的初始化开发版本，并在后续的每次发行时递增次版本号。 - -#### 如何判断发布 1.0.0 版本的时机？ - -当你的软件被用于正式环境，它应该已经达到了 1.0.0 版。如果你已经有个稳定的 API 被使用者依赖，也会是 1.0.0 版。如果你很担心向下兼容的问题，也应该算是 1.0.0 版了。 - -#### 这不会阻碍快速开发和迭代吗？ - -主版本号为零的时候就是为了做快速开发。如果你每天都在改变 API，那么你应该仍在主版本号为零的阶段（0.y.z），或是正在下个主版本的独立开发分支中。 - -#### 对于公共 API，若即使是最小但不向下兼容的改变都需要产生新的主版本号，岂不是很快就达到 42.0.0 版？ - -这是开发的责任感和前瞻性的问题。不兼容的改变不应该轻易被加入到有许多依赖代码的软件中。升级所付出的代价可能是巨大的。要递增主版本号来发行不兼容的改版，意味着你必须为这些改变所带来的影响深思熟虑，并且评估所涉及的成本及效益比。 - -#### 为整个公共 API 写文件太费事了 - -为供他人使用的软件编写适当的文件，是你作为一名专业开发者应尽的职责。保持专案高效一个非常重要的部份是掌控软件的复杂度，如果没有人知道如何使用你的软件或不知道哪些函数的调用是可靠的，要掌控复杂度会是困难的。长远来看，使用语义化版本控制以及对于公共 API 有良好规范的坚持，可以让每个人及每件事都运行顺畅。 - -#### 万一不小心把一个不兼容的改版当成了次版本号发行了该怎么办？ - -一旦发现自己破坏了语义化版本控制的规范，就要修正这个问题，并发行一个新的次版本号来更正这个问题并且恢复向下兼容。即使是这种情况，也不能去修改已发行的版本。可以的话，将有问题的版本号记录到文件中，告诉使用者问题所在，让他们能够意识到这是有问题的版本。 - -#### 如果我更新了自己的依赖但没有改变公共 API 该怎么办？ - -由于没有影响到公共 API，这可以被认定是兼容的。若某个软件和你的包有共同依赖，则它会有自己的依赖规范，作者也会告知可能的冲突。要判断改版是属于修订等级或是次版等级，是依据你更新的依赖关系是为了修复问题或是加入新功能。对于后者，我经常会预期伴随着更多的代码，这显然会是一个次版本号级别的递增。 - -#### 如果我变更了公共 API 但无意中未遵循版本号的改动怎么办呢？（意即在修订等级的发布中，误将重大且不兼容的改变加到代码之中） - -自行做最佳的判断。如果你有庞大的使用者群在依照公共 API 的意图而变更行为后会大受影响，那么最好做一次主版本的发布，即使严格来说这个修复仅是修订等级的发布。记住， 语义化的版本控制就是透过版本号的改变来传达意义。若这些改变对你的使用者是重要的，那就透过版本号来向他们说明。 - -#### 我该如何处理即将弃用的功能？ - -弃用现存的功能是软件开发中的家常便饭，也通常是向前发展所必须的。当你弃用部份公共 API 时，你应该做两件事：（1）更新你的文件让使用者知道这个改变，（2）在适当的时机将弃用的功能透过新的次版本号发布。在新的主版本完全移除弃用功能前，至少要有一个次版本包含这个弃用信息，这样使用者才能平顺地转移到新版 API。 - -#### 语义化版本对于版本的字串长度是否有限制呢？ - -没有，请自行做适当的判断。举例来说，长到 255 个字元的版本已过度夸张。再者，特定的系统对于字串长度可能会有他们自己的限制。 +参考[语义化版本 2.0.0](https://semver.org/lang/zh-CN/#%E8%AF%AD%E4%B9%89%E5%8C%96%E7%89%88%E6%9C%AC-200)。 diff --git a/wiki/getting-started/Git/高级/协作规范/贡献者协议（Contributing）.md b/wiki/getting-started/Git/高级/协作规范/贡献者协议（Contributing）.md index b9abe57e..e09ed1f7 100644 --- a/wiki/getting-started/Git/高级/协作规范/贡献者协议（Contributing）.md +++ b/wiki/getting-started/Git/高级/协作规范/贡献者协议（Contributing）.md @@ -1,29 +1,49 @@ --- -id: 贡献者协议（Contributing） title: 贡献者协议（Contributing） +description: Git 协作贡献者协议（Contributing） +keywords: +- Git +- 协作规范 +- 贡献者协议 +tags: +- 协作规范 sidebar_position: 6 -data: 2022年6月15日 +author: 7Wate +date: 2023-06-26 --- +开源项目的成功在很大程度上取决于社区的参与和贡献。然而，这种参与经常涉及到一些复杂的法律问题，尤其是与知识产权有关的问题。为了解决这些问题，开源社区引入了两种主要的贡献者协议：CLA (Contributor License Agreement) 和 DCO (Developer Certificate of Origin)。这两种协议在法律义务和责任方面有着显著的不同。 -## 规范 +## CLA -- 文件命名：CONTRIBUTING.md +CLA (Contributor License Agreement)是开源协议的补充，它明确了贡献者和项目所有者之间的法律关系。CLA 协议包括公司级别和个人级别的 CLA，公司级别的 CLA 允许一个公司代表其所有员工签署，而个人级别的 CLA 则只针对个人贡献者。 -目前参考大厂协议，可根据项目自定义。 +CLA 协议主要涵盖以下几点： -[阿里巴巴 CLA 协议](https://github.com/aliyun/cla) +- 签署该 CLA 的主体和贡献的定义； +- 授予著作权给拥有该软件知识产权的公司或组织； +- 专利许可的授予； +- 签署者保证依法有权授予上述许可； +- 签署者确保所有的贡献内容均为原创作品； +- 签署者为贡献内容支持的免责描述； +- 说明贡献者提交非原创作品应该采用的方式； +- 保证在获悉任何方面不准确的事实或情况之时通知签约方。 -[谷歌 CLA 协议](https://cla.developers.google.com/clas) +对于在中国的企业，他们还会在 CLA 协议中加入一些本地化的内容，比如阿里巴巴的 [Alibaba Open Source Individual CLA](https://github.com/aliyun/cla)。 -## 贡献协议简介 +## DCO -- 开源贡献协议有 CLA（Contributor License Agreement）和 [DCO](https://developercertificate.org/) （Developer Certificate of Origin）两种； -- DCO 由 Linux Foundation 提出，是固定的简短条文（只有4条），旨在让贡献者保证遵守开源 license； -- CLA 是对开源 license 的法律性质补充，由法务制定； -- CLA 可以自定义，不论是个人还是企业级签署的时候都需要提供详细的信息，如姓名、公司、邮箱、地址、电话等； -- 下表中对比了 CLA 和 DCO 的特性，推荐大型跨公司开源项目使用 CLA，利用项目更加正规和长久发展； +DCO (Developer Certificate of Origin)是由 Linux Foundation 制定的，它并不是一个法律协议，而是一种证明。开源贡献者只需要在提交时签署邮件地址，就相当于确认了他们对提交的贡献拥有相应的权利，并同意该贡献在该项目或涉及的开源许可下公开发布。 -开源社区的贡献者协议一般分为两种 CLA 和 DCO，这两种协议各有优缺点如下。 +DCO 包含以下四点保证： + +1. 贡献全部或部分由我创建，我有权根据文件中指明的开源许可提交； +2. 贡献是基于以前的工作，这些工作属于适当的开源许可，无论这些工作全部还是部分由我完成，我有权根据相同的开源许可证（除非我被允许根据不同的许可证提交）提交修改后的工作； +3. 贡献由1、2、或 3 证明的其他人直接提供给我，而我没有对其进行修改。 +4. 我理解并同意该项目和贡献是公开的，并且该贡献的记录（包括我随之提交的所有个人信息，包括我的签字）将无限期保留，并且可以与本项目或涉及的开源许可证保持一致或者重新分配。 + +## CLA 与 DCO 的比较 + +下表对比了 CLA 和 DCO 的特性，可以看出两者在法律责任、社区属性、签署方式等方面都有不同。这就需要根据项目的特点和需求来选择合适的贡献协议。 | 特性 | CLA | DCO | | :----------- | :------------------------------------------------- | :--------------------------------------------------------- | @@ -34,33 +54,48 @@ data: 2022年6月15日 | 使用案例 | Google、Pivotal、CNCF、阿里巴巴、Apache SkyWalking | GitLab、Chef、Harbor、TiKV | | 公司属性 | 强，可以签署公司级别的 CLA | 弱 | -### CLA +在选择合适的贡献协议时，不仅要考虑法律问题，也要考虑社区的文化和参与者的需求。例如，对于大型跨公司开源项目来说，CLA 可能更适合，因为它可以让项目更加正规，并且更符合长期发展的需求。而对于那些更依赖社区的项目来说，DCO 由于其简洁和易于理解的优点，可能会是更好的选择。 -CLA 是 Contributor License Agreement 的缩写，CLA 可以看做是对开源软件本身采用的开源协议的补充。一般分为公司级和个人级别的 CLA，所谓公司级即某公司代表签署 CLA 后即可代表该公司所有员工都签署了该 CLA，而个人级别 CLA 只代表个人认可该 CLA。 +## 贡献者协议 -因为 CLA 是每个公司或组织自定义的，在细节上可能稍有不同，不过总体都包含以下内容： +文件通常被命名为 `CONTRIBUTING.md`，这个文件通常位于项目的根目录中。有一些项目可能会使用不同的文件名，例如 `CONTRIBUTORS.txt` 或 `CONTRIBUTE.md`，但是 `CONTRIBUTING.md` 是最常见的约定。 -- 关于签署该 CLA 的主体和贡献的定义； -- 授予著作权给拥有该软件知识产权的公司或组织； -- 专利许可的授予； -- 签署者保证依法有权授予上述许可； -- 签署者确保所有的贡献内容均为原创作品； -- 签署者为贡献内容支持的免责描述； -- 说明贡献者提交非原创作品应该采用的方式； -- 保证在获悉任何方面不准确的事实或情况之时通知签约方； +### 中文模板 -对于主体在中国的企业，还加入了一些本地化的内容，如 [Alibaba Open Source Individual CLA](https://github.com/aliyun/cla) 。 +```markdown +贡献者许可协议 -因为 CLA 分别为个人级和公司级，所以对于不同名义签署时需要提供不同的信息。签署个人级 CLA 的时候需要提供个人信息（姓名、地址、邮箱、电话等），签署公司级 CLA 还需要提供公司信息（名称、地址、联系电话、邮箱、传真等）； +本贡献者许可协议（以下简称“协议”）由签署下列的一方（以下简称“贡献者”）同意，并向[项目名称]授予对由[项目名称]管理的软件项目的某些许可权。本协议自下列最新的签名日期起生效。 -### DCO +1. 定义： + “代码”指的是在此协议下由贡献者交付给[项目名称]的计算机软件代码，无论是以人类可读形式还是机器可执行形式。 -DCO 是 Developer Certificate of Origin 的缩写，由 Linux Foundation 于 2004 年制定。DCO 最大的优点是可以减轻开发者贡献的阻碍，不用阅读冗长的 CLA 法律条文，只需要在提交的时候签署邮件地址即可。Chef 和 GitLab 已分别于 2016 年和 2017 年从 CLA 迁移到 DCO。 +2. 版权授予：在此协议的条款和条件下，贡献者特此向[项目名称]和[项目名称]分发的软件的接收者授予永久的，全球性的，非独占的，免费的，免版税的，不可撤销的版权许可，用于复制，准备衍生作品，公开展示，公开表演，再许可，和分发代码及其衍生作品。 -[DCO](https://developercertificate.org/) 目前是 1.1 版本，内容很简单，开源项目的贡献者只需要保证以下四点： +贡献者声明贡献者有法律权利授予上述许可。 -1. 该贡献全部或部分由我创建，我有权根据文件中指明的开源许可提交；要么 -2. 该贡献是基于以前的工作，这些工作属于适当的开源许可，无论这些工作全部还是部分由我完成，我有权根据相同的开源许可证（除非我被允许根据不同的许可证提交）提交修改后的工作；要么 -3. 该贡献由1、2、或 3 证明的其他人直接提供给我，而我没有对其进行修改。 -4. 我理解并同意该项目和贡献是公开的，并且该贡献的记录（包括我随之提交的所有个人信息，包括我的签字）将无限期保留，并且可以与本项目或涉及的开源许可证保持一致或者重新分配。 +贡献者名称：__________ +签名：__________ +日期：__________ +``` + +### 英文模板 + +```markdown +Contributor License Agreement + +This Contributor License Agreement ("Agreement") is agreed to by the party signing below ("Contributor"), and conveys certain license rights to [Project Name] for software projects managed by [Project Name]. This Agreement is effective as of the latest signature date below. + +1. Definitions: + "Code" means the computer software code, whether in human-readable or machine-executable form, that is delivered by Contributor to [Project Name] under this Agreement. + +2. Copyright Grant: Subject to the terms and conditions of this Agreement, Contributor hereby grants to [Project Name] and to recipients of software distributed by [Project Name], a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Code and such derivative works. + +Contributor represents that Contributor is legally entitled to grant the above license. + +Contributor Name: __________ +Signature: __________ +Date: __________ + +``` diff --git a/wiki/getting-started/文档/文档内容.md b/wiki/getting-started/文档/文档内容.md index a8a84a8d..13dd270f 100644 --- a/wiki/getting-started/文档/文档内容.md +++ b/wiki/getting-started/文档/文档内容.md @@ -390,21 +390,21 @@ date: 2023-06-26 - 英文大小写形式不能写错。 -> 错误示例：用户可以在 mysql 数据库中创建新的表。❌ +> 用户可以在 mysql 数据库中创建新的表。❌ > -> 正确示例：用户可以在 MySQL 数据库中创建新的表。 +> 用户可以在 MySQL 数据库中创建新的表。 - 当中文句子中夹有英文单词或词组时，无论该英文单词或词组位于中文句子的开头、中间还是末尾，普通单词、词组必须小写；专有名词等在英文中必须大写的单词或词组，保留其大写形式。 -> 错误示例：在 SQL 语句中，你可以使用 "SELECT" 语句获取数据。❌ +> 在 SQL 语句中，你可以使用 "SELECT" 语句获取数据。❌ > -> 正确示例：在 SQL 语句中，你可以使用 "select" 语句获取数据。 +> 在 SQL 语句中，你可以使用 "select" 语句获取数据。 - 当中文句子中夹有完整的英文句子时，无论该英文句子位于中文句子的开头、中间还是末尾，其首字母均保留大写形式。 -> 错误示例：如需更多信息，请参阅 "in this chapter, we will learn how to create tables."❌ +> 如需更多信息，请参阅 "in this chapter, we will learn how to create tables."❌ > -> 正确示例：如需更多信息，请参阅 "In this chapter, we will learn how to create tables." +> 如需更多信息，请参阅 "In this chapter, we will learn how to create tables." ## 语法