diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 14cd45d..e89a1c9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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' \ ```
-查看响应示例: +查看响应示例: ```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 中存在), 以便后续 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 后出现重复相同提交的问题