feat(CONTRIBUTING.md): 更加严谨的表述
This commit is contained in:
SessionHu
parent
52f0b45812
commit
612d59101f
@ -1,6 +1,6 @@
|
||||
# 贡献指南
|
||||
|
||||
欢迎来到 bilibili-API-collect 社区贡献指南，本文主要面向需要进行提交贡献文档内容的用户。
|
||||
欢迎来到 bilibili-API-collect 社区贡献指南，本文主要面向想要对本项目参与贡献的用户, 请务必认真阅读本文正文与潜在的注释
|
||||
|
||||
## 总则
|
||||
|
||||
@ -12,7 +12,7 @@
|
||||
|
||||
## Issue、Discussion 与社群讨论
|
||||
|
||||
对文档内容存在**不理解**之处、以及发现文档内容有所**缺失**或**错误**，可直接提出，强烈建议以提交 **Issue** 的形式添加 / 补充 / 更新文档中的说明，以发起 **Discussion** 的形式提出问题、代码用例、情报分享，并希望关于本项目的各种交流都是**公开进行**的，因为这样才可以保证关键信息的一致性。
|
||||
对文档内容存在**不理解**之处、以及发现文档内容有所**缺失**或**错误**，可直接提出，强烈建议以提交 **Issue** 的形式 添加 / 补充 / 更新 文档中的说明，以发起 **Discussion** 的形式提出问题、代码用例、情报分享，并希望关于本项目的各种交流都是**公开进行**的，因为这样才可以保证关键信息的一致性。
|
||||
|
||||
提交 Issue 请遵守以下原则：
|
||||
|
||||
@ -57,7 +57,7 @@ Telegram 交流群主要用作 [BAC 项目](https://github.com/SocialSisterYi/bi
|
||||
|
||||
### 目录
|
||||
|
||||
文档目录以 **Markdown 无序列表**语法写在 [README.md](README.md) 中，使用缩进标识文档的层级，如 `视频` 下存在 `基本信息`、`快照`、`视频推荐`、`TAG` 等子分类，使用 **Markdown 复选框**语法该标注文档是否编写完成
|
||||
文档目录以 **Markdown 无序列表**语法写在 [README.md](README.md) 中，使用缩进标识文档的层级，如 `视频` 下存在 `基本信息`、`快照`、`视频推荐`、`TAG` 等子分类，使用 **Markdown 复选框**语法该标注文档是否编写完成, 新文档写完后记得在目录添加入口
|
||||
|
||||
```markdown
|
||||
- [ ] 视频
|
||||
@ -97,9 +97,9 @@ Telegram 交流群主要用作 [BAC 项目](https://github.com/SocialSisterYi/bi
|
||||
|
||||
接口说明分为 `标题`、`地址`、`说明`、`请求参数`、`响应正文`、`示例` 这些部分
|
||||
|
||||
接口标题为**二级以下**的标签，接口地址使用**引用**语法，地址只保留 REST API 路径，不应携带 query 等内容
|
||||
接口标题为**二级以下**的标签<!--别顶着一级标题就开写-->，接口地址使用**块引用**语法，地址只保留 REST API 路径，不应携带 query 等内容
|
||||
|
||||
接口地址下方需要注明接口的请求方式，如 `GET`、`POST`、`PUT` 等，使用*斜体*语法
|
||||
接口地址下方需要注明接口的请求方法，如 `GET`、`POST`、`PUT` 等，使用*斜体*语法
|
||||
|
||||
若接口存在认证或鉴权，需要在说明中注明，如 `Cookie (SESSDATA)`、`APP`（认证是针对用户的，鉴权是针对接口使用的）
|
||||
|
||||
@ -112,16 +112,16 @@ e.g.：
|
||||
|
||||
> https://api.bilibili.com/x/web-interface/view
|
||||
|
||||
*请求方式：GET*
|
||||
*请求方法: GET*
|
||||
|
||||
认证方式：Cookie (SESSDATA)
|
||||
认证方式: Cookie (SESSDATA)
|
||||
|
||||
限制游客访问的视频需要登录
|
||||
```
|
||||
|
||||
**请求参数**应在**接口说明**的下方，应注明参数类型 url 参数或正文参数（正文参数应注明 content-type，如 `application/x-www-form-urlencoded` 或 `multipart/form-data`），使用**加粗**语法
|
||||
**请求参数**应在**接口说明**的下方，应注明参数类型 URL 参数或正文参数（正文参数应注明 `Content-Type`，如 `application/x-www-form-urlencoded` 或 `multipart/form-data`），使用**加粗**语法
|
||||
|
||||
对象的字段及其含义使用**表格**进行整理，表头统一依次为 `参数名`、`类型`、`内容`、`必要性`、`备注`，类型为 `num`、`str`、`bool`、`nums`、`strs`、`file` 等 (未来可能会统一改为基于 TypeScript 的类型系统)，必要性为 `必要`、`非必要`、`必要 (可选)` 等，表格内每个字段为一行
|
||||
对象的字段及其含义使用**表格**进行整理，表头统一依次为 `参数名`、`类型`、`内容`、`必要性`、`备注`，类型为 `num`、`str`、`bool`、`nums`、`strs`、`file` 等 (也可以使用基于 TypeScript 的类型系统)，必要性为 `必要`、`非必要`、`必要 (可选)` 等，表格内每个字段为一行
|
||||
|
||||
e.g.：
|
||||
|
||||
@ -134,7 +134,7 @@ e.g.：
|
||||
|
||||
JSON Object 或 ProtoBuf Message 应以对象的**表格**形式书写，表头为 `根对象` 或 `xx 中的 yy 对象` 或 `xx.yy.zz 对象`，若对象位于数组中则为 `xx 数组中的对象` 或 `xx[] 中的对象`
|
||||
|
||||
表头统一依次为 `字段`、`类型`、`内容`、`备注`，类型为 JSON / Protobuf 的标准类型，如 `num`、`str`、`bool`、`obj`、`array`、`null` 等
|
||||
表头统一依次为 `字段`、`类型`、`内容`、`备注`，类型为 JSON / Protobuf 的标准类型，具体同请求参数一致
|
||||
|
||||
不明确定义的字段说明在内容的末尾添加问号，如 `播放数？`；定义尚未明确的字段使用 `（？）` 在内容中占位，并在备注中填写 `作用尚不明确`
|
||||
|
||||
@ -179,7 +179,7 @@ e.g.：
|
||||
e.g.：
|
||||
|
||||
````markdown
|
||||
**示例：**
|
||||
**示例:**
|
||||
|
||||
获取视频 `av85440373` 的基本信息
|
||||
|
||||
@ -189,7 +189,7 @@ curl -G 'https://api.bilibili.com/x/web-interface/view' \
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary>查看响应示例：</summary>
|
||||
<summary>查看响应示例:</summary>
|
||||
|
||||
```jsonc
|
||||
{
|
||||
@ -262,22 +262,24 @@ message Author {
|
||||
|
||||
本项目仓库仅托管于 GitHub, 使用 Git 作为版本控制系统, 你需要对两者有基础的了解
|
||||
|
||||
请先 fork, 然后在自己的 fork 上进行修改
|
||||
请先 fork, 然后在自己的 fork 上进行修改<!--废话-->
|
||||
|
||||
提交的标题不要使用默认的 `Update xxx`, 建议遵循 [Conventional Commits (约定式提交) 规范](https://www.conventionalcommits.org/zh-hans/v1.0.0/), 标题语言可根据个人习惯
|
||||
提交的标题不要使用默认的 `Update xxx`, 请遵循 [Conventional Commits (约定式提交) 规范](https://www.conventionalcommits.org/zh-hans/v1.0.0/), 标题语言可根据个人习惯
|
||||
|
||||
<!--下面这两段属于常识, 但好像还有人不知道-->
|
||||
当发现远程与本地仓库不一致时, 若你操作的 fork 的 branch 无打开的 PR, 建议使用变基拉取, 而不是生成一个额外的合并提交的合并拉取, 反之则相反
|
||||
|
||||
移动文件请使用 `git mv`, 而不是删除并添加同一个文件于不同位置 (该问题在 VSCode 的 GUI 版 Git 中存在)
|
||||
移动文件请使用 `git mv`, 而不是删除并添加同一个文件于不同位置 (该问题在 VSCode 的 GUI 版 Git 中存在<!--某个易姓owner干过-->), 以便后续 blame 操作
|
||||
|
||||
### 拉取请求 (Pull Request)
|
||||
|
||||
使用 拉取请求 (Pull Request, PR) 将修改后的文档提交到 `master` 分支，标题需写明修改或新增的内容, `gh_pages` 分支将在 PR 合并后自动更新
|
||||
使用 拉取请求 (Pull Request, PR) 将修改后的文档提交到 `master` 分支，标题需写明修改或新增的内容, 同样也需要遵循约定式提交规范, `gh_pages` 分支将在 PR 合并后自动更新
|
||||
|
||||
如果你还没有完成计划的全部修改, 请创建 Draft Pull Request 表示你还没有做好被合并的准备 ~~(抢占先机, 精神可嘉, 值得鼓励)~~
|
||||
|
||||
PR 正文使用 **无序列表** 写明更改的每一项内容, 可以使用复选框表明进度, 需要关闭的 Issue 请使用 `close #xxxx` 这样的格式一并包含在内
|
||||
|
||||
如果内容包含代码, 请一并提供测试的输入与输出的文本或截图, 最好可以附上完整的测试环境及相关可执行文件等
|
||||
如果内容包含代码等, 请一并提供测试的输入与输出的文本或截图, 最好可以附上完整的测试环境及相关可执行文件等
|
||||
|
||||
<!--这也是常识喵-->
|
||||
PR 合并后, 请及时删除或更新分支. 特别是在使用压缩合并或变基合并后, 请 `Discard changes` 或直接删除分支, 以免在下一次 PR 后出现重复相同提交的问题
|
||||
|
||||
Loading…
Reference in New Issue
Block a user