From d9f127f19f24eaf4056095b677b47cb06a643717 Mon Sep 17 00:00:00 2001 From: 7Wate Date: Mon, 11 Jul 2022 14:36:46 +0800 Subject: [PATCH] =?UTF-8?q?Git=EF=BC=9A=E6=B3=A8=E9=87=8A=EF=BC=88Comments?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- org/标准/Git 协作规范/交流反馈（Issue）.md | 23 ++--- org/标准/Git 协作规范/关于（Readme）.md | 39 +++++++- .../{分支模型（Branch）.md => 分支（Branch）.md} | 32 +++---- org/标准/Git 协作规范/开源协议（License）.md | 8 +- .../{提交日志（Commit）.md => 日志（Commit）.md} | 6 +- org/标准/Git 协作规范/注释（Comments）.md | 87 +++++++++++++++++ org/标准/Git 协作规范/版本号（Tag）.md | 8 -- org/标准/Git 协作规范/版本（Tag）.md | 96 +++++++++++++++++++ .../Git 协作规范/贡献者协议（Contributing）.md | 19 ++-- 9 files changed, 263 insertions(+), 55 deletions(-) rename org/标准/Git 协作规范/{分支模型（Branch）.md => 分支（Branch）.md} (89%) rename org/标准/Git 协作规范/{提交日志（Commit）.md => 日志（Commit）.md} (95%) create mode 100644 org/标准/Git 协作规范/注释（Comments）.md delete mode 100644 org/标准/Git 协作规范/版本号（Tag）.md create mode 100644 org/标准/Git 协作规范/版本（Tag）.md diff --git a/org/标准/Git 协作规范/交流反馈（Issue）.md b/org/标准/Git 协作规范/交流反馈（Issue）.md index 54931099..be22129e 100644 --- a/org/标准/Git 协作规范/交流反馈（Issue）.md +++ b/org/标准/Git 协作规范/交流反馈（Issue）.md @@ -2,19 +2,20 @@ id: 交流反馈（Issue） title: 交流反馈（Issue） data: 2022年6月15日 -sidebar_position: 4 +sidebar_position: 5 --- -## 新需求（Pull Request） +## 规范 -### 标题 +- 文件命名：ISSUE.md + + +### 新需求（Pull Request） 规范：`Pr:title` 示例：`Pr(auth):role-based authorization` -### 内容 - ```markdown ## 背景 @@ -30,18 +31,14 @@ sidebar_position: 4 附上对应的 Pull Request 地址。 ``` -## 反馈缺陷（Bug） +### 反馈缺陷（Bug） 请务必先阅读**提问的智慧！** -### 标题 - 规范：`Bug:title` 示例：`Bug(login):Admin password cannot be reset` -### 内容 - ```markdown ## 运行环境 @@ -61,18 +58,14 @@ sidebar_position: 4 - 报错信息、日志等 ``` -## 答疑交流（Usage） +### 答疑交流（Usage） 一般来说，更推荐使用社区自助交流方式。 -### 标题 - 规范：`Usage:title` 示例：`Usage(update):1.2.3 version update failed` -### 内容 - ```markdown ## 运行环境 diff --git a/org/标准/Git 协作规范/关于（Readme）.md b/org/标准/Git 协作规范/关于（Readme）.md index 5156a007..2d8c25c0 100644 --- a/org/标准/Git 协作规范/关于（Readme）.md +++ b/org/标准/Git 协作规范/关于（Readme）.md @@ -2,18 +2,22 @@ id: 关于（Readme） title: 关于（Readme） data: 2022年6月15日 -sidebar_position: 5 +sidebar_position: 4 --- -## 关于（Readme） +## 规范 -国际化项目关于文档尽量采用双语（英文 + 中文），文件命名格式：readme_EN.md、readme_ZH.md。 +- 文件命名：README.md、README_EN.md，根据项目受众群体标定关于文档的默认语言。 +- 徽章：[https://shields.io/](https://shields.io/) + +### 中文模板 ```markdown ## 项目 ### 徽章 ### 简介 + ### 演示 ### 原理图 / 流程图 ## 用法 @@ -34,3 +38,32 @@ sidebar_position: 5 ## 协议 ``` + +### 英文模板 + +```markdown +## Project + + ### Badges + ### Introduction + ### Demo + ### Schematic / Flowchart + +## Usage + + ### Install + ### Documentation + ### F&Q + +## Map + + ### Development map + ### Update history (can be a separate file) + +## Contribute + +## Thanks + +## License +``` + diff --git a/org/标准/Git 协作规范/分支模型（Branch）.md b/org/标准/Git 协作规范/分支（Branch）.md similarity index 89% rename from org/标准/Git 协作规范/分支模型（Branch）.md rename to org/标准/Git 协作规范/分支（Branch）.md index 9d08b6e9..b5a4caf2 100644 --- a/org/标准/Git 协作规范/分支模型（Branch）.md +++ b/org/标准/Git 协作规范/分支（Branch）.md @@ -1,12 +1,26 @@ --- -id: 分支模型（Branch） -title: 分支模型（Branch） +id: 分支（Branch） +title: 分支（Branch） sidebar_position: 1 data: 2022年6月15日 --- +## 规范 + ![Git 分支工作流.png](https://static.7wate.com/img/2021/08/24/c5a50e99dde5f.png) +主分支命名：`master `、`main` + +开发分支命名：`develop` + +功能分支命名：除 `master`、`main`、`develop`、`release-*`、`hotfix-*` 以外的任何名字 + +预发布分支命名：`release-*` + +热修复分支命名：`hotfix-*` + +防止产生歧义，**建议禁止简拼。** + ## 主要分支 在中央仓库中有两个生命期无限长的主要分支： @@ -61,17 +75,3 @@ data: 2022年6月15日 当完成了紧急 bug 的修复时，要将该热修复分支合并回 `master` 分支，**并且同时也要将其合并回 `develop` 分支**，以确保对该 bug 的修复也同时包含在下一次发版中。**如果此时同时存在一个预发布分支，那么要把该热修复分支合并回该预发布分支，而不是 `develop` 分支**。 最后就可以删掉该热修复分支了。 - -## 命名规范 - -主分支：`master / main` - -开发分支：`develop` - -功能分支：除 `master`、`develop`、`release-*`、`hotfix-*` 以外的任何名字 - -预发布分支：`release-*` - -热修复分支：`hotfix-*` - -**防止产生歧义，禁止简拼。** diff --git a/org/标准/Git 协作规范/开源协议（License）.md b/org/标准/Git 协作规范/开源协议（License）.md index be90f818..0d388f7f 100644 --- a/org/标准/Git 协作规范/开源协议（License）.md +++ b/org/标准/Git 协作规范/开源协议（License）.md @@ -2,9 +2,13 @@ id: 开源协议（License） title: 开源协议（License） data: 2022年6月15日 -sidebar_position: 6 +sidebar_position: 7 --- +## 规范 + ![快速选择开源协议](https://static.7wate.com/img/2020/07/02/fe11588b073bf.png) -许可证向导：https://kaiyuanshe.cn/license-tool/ \ No newline at end of file +- 文件命名：LICENSE +- 许可证向导：https://kaiyuanshe.cn/license-tool/ + diff --git a/org/标准/Git 协作规范/提交日志（Commit）.md b/org/标准/Git 协作规范/日志（Commit）.md similarity index 95% rename from org/标准/Git 协作规范/提交日志（Commit）.md rename to org/标准/Git 协作规范/日志（Commit）.md index a2ff341d..ba94e2a9 100644 --- a/org/标准/Git 协作规范/提交日志（Commit）.md +++ b/org/标准/Git 协作规范/日志（Commit）.md @@ -1,11 +1,11 @@ --- -id: 提交日志（Commit） -title: 提交日志（Commit） +id: 日志（Commit） +title: 日志（Commit） sidebar_position: 2 data: 2022年6月15日 --- -## Commit 日志 +## 规范 项目日志所有内容务必使用 **ASCII** 字符，尽量不要使用中文或 emoji，要求**最大化兼容**，便于程序处理。 diff --git a/org/标准/Git 协作规范/注释（Comments）.md b/org/标准/Git 协作规范/注释（Comments）.md new file mode 100644 index 00000000..fc6861d9 --- /dev/null +++ b/org/标准/Git 协作规范/注释（Comments）.md @@ -0,0 +1,87 @@ +--- +id: 注释（Comments） +title: 注释（Comments） +sidebar_position: 1.5 +data: 2022年7月11日 +--- +## 规范 + +**代码**就是**最好的注释**，尽量使用**英文注释**，坚决**不滥用**注释。**不需要**标明**作者、时间、改动记录**，请把这些放在 **Git** 对应**提交日志**中！ + +### 代码注释 + +#### 行注释 + +行注释位于该**行代码前**，建议切勿代码后注释。 + +规范： + +```javascript +// 注释文字 +代码 +``` + +示例： + +```javascript +// 启用便携式支持 +const portable = bootstrapNode.configurePortable(product); +``` + +#### 关键字注释 + +注释块**尾部**，关键字前添加 `@` 符号。 + +规范： + +```javascript +/* + * 注释 + * @type{变量} 注释 + * @param{变量} 注释 + * @returns{变量} 注释 + */ +``` + +示例： + +```javascript +/* + * @param {string} dir + * @returns {Promise} + */ +function mkdirp(dir) { + return new Promise((resolve, reject) => { + fs.mkdir(dir, { recursive: true }, err => (err && err.code !== 'EEXIST') ? reject(err) : resolve(dir)); + }); +} +``` + +### 版权注释 + +版权注释位于**代码文件首行**。 + +规范： + +```javascript +/*---------------- + * 版权归 XX 所有 + * 遵循 XX 开源协议 + *----------------*/ + +代码··· +``` + +上下分割线要求是描述文字长度 1.1 倍，`/* */` 不令其一行，描述文字前保持 1 个空格。 + +示例： + +```javascript +/*--------------------------------------------------------------------------------------- + * Copyright (c) Microsoft Corporation. All rights reserved. + * Licensed under the MIT License. See License.txt in the project root for license information. + *---------------------------------------------------------------------------------------*/ + +const perf = require('./vs/base/common/performance'); +perf.mark('code/didStartMain'); +``` diff --git a/org/标准/Git 协作规范/版本号（Tag）.md b/org/标准/Git 协作规范/版本号（Tag）.md deleted file mode 100644 index 33e6a1ca..00000000 --- a/org/标准/Git 协作规范/版本号（Tag）.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -id: 版本号（Tag） -title: 版本号（Tag） -data: 2022年6月15日 -sidebar_position: 7 ---- - -![语义化版本.png](https://static.7wate.com/img/2021/08/24/ad4999467e192.png) \ No newline at end of file diff --git a/org/标准/Git 协作规范/版本（Tag）.md b/org/标准/Git 协作规范/版本（Tag）.md new file mode 100644 index 00000000..93372966 --- /dev/null +++ b/org/标准/Git 协作规范/版本（Tag）.md @@ -0,0 +1,96 @@ +--- +id: 版本（Tag） +title: 版本（Tag） +data: 2022年6月15日 +sidebar_position: 3 +--- + +## 规范 + +![语义化版本.png](https://static.7wate.com/img/2021/08/24/ad4999467e192.png) + +首发版本以 **0.1.0** 开始，版本格式：主版本号.次版本号.修订号，递增规则如下： + +1. 主版本号：当你做了不兼容的 API 修改， +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 个字元的版本已过度夸张。再者，特定的系统对于字串长度可能会有他们自己的限制。 diff --git a/org/标准/Git 协作规范/贡献者协议（Contributing）.md b/org/标准/Git 协作规范/贡献者协议（Contributing）.md index 81e2dc08..b9abe57e 100644 --- a/org/标准/Git 协作规范/贡献者协议（Contributing）.md +++ b/org/标准/Git 协作规范/贡献者协议（Contributing）.md @@ -1,10 +1,20 @@ --- id: 贡献者协议（Contributing） title: 贡献者协议（Contributing） -sidebar_position: 3 +sidebar_position: 6 data: 2022年6月15日 --- +## 规范 + +- 文件命名：CONTRIBUTING.md + +目前参考大厂协议，可根据项目自定义。 + +[阿里巴巴 CLA 协议](https://github.com/aliyun/cla) + +[谷歌 CLA 协议](https://cla.developers.google.com/clas) + ## 贡献协议简介 - 开源贡献协议有 CLA（Contributor License Agreement）和 [DCO](https://developercertificate.org/) （Developer Certificate of Origin）两种； @@ -54,10 +64,3 @@ DCO 是 Developer Certificate of Origin 的缩写，由 Linux Foundation 于 200 3. 该贡献由1、2、或 3 证明的其他人直接提供给我，而我没有对其进行修改。 4. 我理解并同意该项目和贡献是公开的，并且该贡献的记录（包括我随之提交的所有个人信息，包括我的签字）将无限期保留，并且可以与本项目或涉及的开源许可证保持一致或者重新分配。 -## 协议标准 - -目前参考大厂协议，可根据项目自定义。 - -[阿里巴巴 CLA 协议](https://github.com/aliyun/cla) - -[谷歌 CLA 协议](https://cla.developers.google.com/clas) \ No newline at end of file