diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 67dd0d6a93..b6e92abfac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,10 @@ # 代码贡献指南 +Bilibili Evolved 是一个基于 Web 前端技术构建的油猴脚本, 贡献代码前应具备的相关能力有: +- 了解最基础的油猴脚本的开发流程, 包括理解 [UserScript Header 和 GM API](https://www.tampermonkey.net/documentation.php?locale=en). +- 熟悉 Web 前端技术, 编写逻辑时使用 [TypeScript](https://www.typescriptlang.org/), 编写样式时使用 [Scss](https://sass-lang.com/), 创建 UI 时使用 [Vue 2](https://v2.cn.vuejs.org/). +- 新增的代码能够通过 [ESLint](https://eslint.org/) 和 [TypeScript](https://www.typescriptlang.org/) 检查. + ## 搭建开发环境 - 需要安装 [Node.js](https://nodejs.org/en/download/) (>= 14.0), [Visual Studio Code](https://code.visualstudio.com/) 和 [pnpm](https://pnpm.io/installation). @@ -13,6 +18,10 @@ cd registry pnpm install ``` +- [配置 VS Code 插件](https://code.visualstudio.com/docs/editor/extension-marketplace): + - [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint), 用于格式化 TypeScript 和 Vue 文件. + - [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode), 用于格式化 Scss 和其他文件. + ### 本体 需要说明的是, 脚本本体和功能是分开的两个项目. 本体的代码在 `src/` 下, 开发时产生 `dist/bilibili-evolved.dev.user.js` 文件. 功能的代码位于 `registry/` 下, 开发时在 `registry/dist/` 下产生文件. > 如果不使用 Visual Studio Code, 则需要根据 `.vscode/tasks.json` 中各个任务定义的命令手动在终端执行. (npm scripts 仅用于 CI) @@ -20,10 +29,11 @@ pnpm install 配置本地调试环境: **如果使用的是基于 Chromium 的浏览器** -1. Chrome 插件管理 `chrome://extensions/` > Tampermonkey > 详细信息 -2. 打开 `允许访问文件网址` -3. 新建脚本 -4. 粘贴内容: +1. VS Code 中运行 `启动开发服务 dev-server` 任务, 会在项目的 `dist/` 文件夹下生成一个开发用的脚本 `dist/bilibili-evolved.dev.user.js`. +2. Chrome 插件管理 `chrome://extensions/` > Tampermonkey > 详细信息 +3. 打开 `允许访问文件网址` +4. 新建脚本 +5. 粘贴内容: ```js // ==UserScript== // @name Bilibili Evolved (Local) @@ -63,24 +73,20 @@ pnpm install // @connect localhost // @connect * // @require https://raw.githubusercontent.com/lodash/lodash/4.17.15/dist/lodash.min.js +// @require file://{{ bilibili-evolved.dev.user.js的绝对路径 }} // @icon https://raw.githubusercontent.com/the1812/Bilibili-Evolved/preview/images/logo-small.png // @icon64 https://raw.githubusercontent.com/the1812/Bilibili-Evolved/preview/images/logo.png -// @require file://{{ bilibili-evolved.dev.user.js的绝对路径 }} // ==/UserScript== ``` -6. 在那些 `@require` 下面再添加一行 `@require file://{{ bilibili-evolved.dev.user.js的绝对路径 }}` -> Windows 例子: `@require file://C:/xxx/Bilibili-Evolved/bilibili-evolved.dev.user.js` - -> macOS 例子: `@require file:///Users/xxx/Documents/Bilibili-Evolved/bilibili-evolved.dev.user.js` -> 上面那些其他的 @require 跟 `src/client/common.meta.json` 里的保持一致就行, 偶尔这些依赖项会变动导致这个本地调试脚本失效, 到时候照着改一下就行. +6. 将里面的 `{{ bilibili-evolved.dev.user.js的绝对路径 }}` 替换为第一步生成的文件的真实路径. +> Windows 例子: `@require file://C:/xxx/Bilibili-Evolved/dist/bilibili-evolved.dev.user.js` -> 必须放到// ==/UserScript== 之前 不然会加载不到该脚本 +> macOS 例子: `@require file:///Users/xxx/Documents/Bilibili-Evolved/dist/bilibili-evolved.dev.user.js` -> 该bilibili-evolved.dev.user.js脚本 需要在vs code->终端>运行任务..->本地:编辑开发版本生成 目录为Bilibili-Evolved/dist/bilibili-evolved.dev.user.js -7. 保存脚本, 运行 `启动开发服务 dev-server` 任务 -8. 进入 b 站, 安装 `DevClient` 组件, 功能中显示已连接时就是成功了 +> 上面那些其他的 @require 跟 `src/client/common.meta.json` 里的保持一致就行, 偶尔这些依赖项会变动导致这个本地调试脚本失效, 到时候照着改一下就行. +7. 进入 b 站, 安装 `DevClient` 组件, 功能中显示已连接时就是成功了 **如果使用 Firefox 或 Safari** 1. 运行 `启动开发服务 dev-server` 任务时, 假设得到的本体链接为 `http://localhost:23333/dist/bilibili-evolved.dev.user.js` @@ -143,6 +149,7 @@ pnpm install ## 可用资源 本体提供了大量 API 供组件 / 插件使用. + ### 全局 全局变量, 无需 `import` 就可以直接使用. (Tampermonkey API 这里不再列出了, 可根据代码提示使用) @@ -235,7 +242,11 @@ pnpm install - `ui/AsyncButton.vue`: `click` 事件为异步函数时, 执行期间自动使 `Button` 禁用, 其他和 `Button` 相同. ## 代码风格检查 -项目中含有 ESLint, 不通过 ESLint 是无法进行 Pull Request 的. 配置基于 `airbnb-base`, `typescript-eslint/recommended`, `vue/recommended` 修改而来, 几个比较特殊的规则如下: +项目中含有 ESLint, 不通过 ESLint 是无法进行 Pull Request 的. + +你可以使用 [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) 插件实时检查当前代码, 也可以运行 `生产:代码检查 prod:lint` 或 `生产:代码修复 prod:lint-fix` 来使用 ESLint 的命令行进行检查. + +配置基于 `airbnb-base`, `typescript-eslint/recommended`, `vue/recommended` 修改而来, 几个比较特殊的规则如下: ### 强制性 - 除了 Vue 单文件组件, 禁止使用 `export default`, 所有导出必须命名. @@ -248,12 +259,11 @@ pnpm install - 不需要使用 `this` 特性的函数, 均使用箭头函数. ## 提交 commit -仅提交源代码上的修改即可, 不建议把 dist 文件夹里的产物也提交, 否则容易在 PR 时产生冲突. +仅提交源代码上的修改即可, 不要把 dist 文件夹里的产物也提交, 产物会在发布新版本时在对应的生产分支上构建. commit message 只需写明改动点, 中英文随意, 也不强求类似 [commit-lint](https://github.com/conventional-changelog/commitlint) 的格式. ## 发起 PR (合并请求) 将你的分支往主仓库的 `preview-features` (新增功能) 或 `preview-fixes` (功能修复) 分支合并就行. -## 自行保留 -你可以选择不将功能代码合并到主仓库, 因此也没有 ESLint 的限制. PR 时仅添加指向你的仓库中的组件信息即可, 具体来说, 是在 `registry/lib/docs/third-party.ts` 中, 往对应数组中添加你的功能的相关信息, 当然别忘了把 `owner` 设为你的 GitHub 用户名. +或者, 也可以选择不将功能代码合并到主仓库, 因此也没有 ESLint 的限制. PR 时仅添加指向你的仓库中的组件信息即可, 具体来说, 是在 `registry/lib/docs/third-party.ts` 中, 往对应数组中添加你的功能的相关信息, 当然别忘了把 `owner` 设为你的 GitHub 用户名.