萌娘百科界面代码库

MoegirlPediaInterfaceCodes

萌娘百科界面代码库

欢迎来到萌娘百科界面代码库，本仓库由萌娘百科界面管理员所组成的团队维护，旨在以自动化的方式减轻维护界面代码的复杂度。

目前只有萌娘百科的界面管理员可以拥有本仓库的读写权限，如果你是萌娘百科的界面管理员但没有权限，你可以向 U:AnnAngela 获取本仓库的读写权限；不过如果你尚不是界面管理员，我们也欢迎你以下列方式参与到本仓库的维护工作中来。

仓库架构 仓库文件架构

本仓库包含多组文件用以实现不同用途，详情见下。

仓库架构详情

.github 文件夹用以保存 GitHub Dependabot 和 GitHub Actions 所需配置文件，其中： .github/workflows/postCommit.yaml 用以保存自动化流程，包含自动配置 Conventional Commits（约定式提交）所需 scope（作用域）信息、自动导入来自 npm 和指定页面的代码、自动补全小工具列表和自动生成 polyfill 文件； .github/workflows/generateUnrecognizableFeatures.yaml 用以定时生成 scripts/generatePolyfill/unrecognizableFeatures.json 以减少生成 polyfill 时的网络请求； .github/workflows/auto_assign.yaml 用以自动对 pull request 和 issue 添加 assignees 和 reviewers（若有）。 .vscode/settings.json 用来保存 Conventional Commits（约定式提交）所需 scope（作用域）信息； scripts 文件夹用以保存流程所需代码，其中： scripts/postCommit/prepareGit.js 用来准备 Github Actions 上的 git 环境，自动生成 author 和 committer 的相关信息； scripts/browserify/index.js 用来通过 browserify 库导入来自 npm 的代码，其目标在 scripts/browserify/targets.yaml 中定义； scripts/prefetch/index.js 用来导入来自指定页面的代码，其目标在 scripts/prefetch/targets.yaml 中定义； scripts/generatePolyfill/index.js 用来自动生成 polyfill 文件，该代码使用了来自《金融时报》的 polyfill.io（Financial-Times/polyfill-service）和 Financial-Times/polyfill-library； scripts/generateGadgetsDefinition/index.js 用来自动补全小工具列表，当发现新增小工具时，该代码会自动将对应小工具插入到 src/gadgets/Gadgets-definition-list.yaml 的响应列表的末尾； scripts/generateConventionalCommitsScopes/index.js 用来自动配置 Conventional Commits（约定式提交）所需 scope（作用域）信息； scripts/postCommit/linguist-generated.js 用来自动生成 .gitattributes 以告知 Github 如何区分代码是否自动生成； scripts/postCommit/push.js 用来推送由 Github Actions 做出的更改； scripts/generateUnrecognizableFeatures/index.js 用来生成 scripts/generatePolyfill/unrecognizableFeatures.json 以减少生成 polyfill 时的网络请求； scripts/emailmapChecker/index.js 用来检查相关用户是否将其萌娘百科用户名和邮箱地址添加到 .mailmap，若当前环境为本地则检测 git 配置文件里的邮箱地址，若当前环境为 Github Actions 则检查相关 commits 的邮箱地址。 scripts/ci/before.js 和 scripts/ci/after.js 用来在 npm run ci 里自动替换 package-lock.json 里的 resolved 对应的 registry 为你本地设置的 registry，有助于加快安装速度。 自动化工具的配置文件： .eslintrc.yaml 配置 eslint，由于所有 Javascript 代码都需经过编译，故其 parserOptions.ecmaVersion 被指定为 latest 以便充分利用最新标准； tsconfig.json 配置 tsc，由于需要生成能通过小工具扩展验证的代码，故其 compilerOptions.target 被指定为 ES3； .stylelintrc.yaml 配置 stylelint； .postcssrc.yaml 配置 postcss； .browserslistrc 配置 autoprifixer 所使用的 browserslist，目前暂定锚定为 defaults 的基础上添加 Chrome >= 70 以适应萌百用户群体。 代码部分： src/gadgets 以文件夹形式保存小工具，每一个文件夹都是一个小工具，里面包含以下内容： definition.yaml 保存小工具配置，包括依赖项、所需权限等，以 _ 开头的键值对是其他配置，如小工具所在的章节等； .eslintrc.yaml （可选）用以阻止 eslint 在某些文件上进行检查，常见于来自 npm 和指定页面的代码； *.js 和 *.css 为小工具代码，文件名为萌娘百科上对应页面的页面名； src/groups 以文件夹形式保存用户组级别代码，每一个文件夹都对应一个子站点，每一个站点文件夹的子文件夹对应一个用户组，里面包含 *.js 和 *.css 等代码，文件名为萌娘百科上对应页面的页面名； src/global 保存全站代码，每一个文件夹都对应一个站点，里面包含 *.js 和 *.css 等代码，文件名为萌娘百科上对应页面的页面名。

本仓库支持同时管理多个子站点的代码：

小工具部分：通过 definition.yaml 的 _sites 属性指定站点； 用户组代码 和 全站代码：通过文件夹名指定站点。 仓库 npm 脚本

本仓库包含下列脚本：

npm run test 方便检测代码错误； npm run format 可修正可被自动修正的错误； npm run ci 可通过临时修改镜像源的方式加快 npm ci 速度。 自动化流程 每周一 00:00 UTC 会自动触发一次 generateUnrecognizableFeatures CI； 每天 00:15 UTC（但愿，Github Actions的 cron 延迟真的好高 _(:з」∠)_）会自动触发一次 postCommit CI； 每提交一次 commit（包括提交 pull request 和在 pull request 里提交新的 commit），postCommit CI 会触发； 当 postCommit CI 检测到新内容时，会自动触发一次 Linter test。 编译流程

机器人通过以下流程编译代码，然后提交到萌百：

执行 tsc --project tsconfig.production.json 以编译 *.js 代码； 执行 npx postcss src/**/*.css --base src/ -d dist/ --verbose 以编译 *.css 代码； 根据模板生成 MediaWiki:Gadgets-definition 页面。

如需手动唤起机器人，请到 post commit CI workflow 处，选择 Branch 为 master，输入值为 true，手动执行该 workflow。

已知问题

TypeScript 5.0 将 target: ES3 编译选项标记为弃用，而萌娘百科目前（2023年3月）使用的 MediaWiki 1.31.7 存在 bug 无法解析使用保留字作为点号属性名（foo.return 会报错），这在 MediaWiki 1.33 被修复。

解决办法：

等萌百升级 MediaWiki 系统；或 找一个支持编译为 ECMAScript 3 版本的编译工具。 参与维护

众人拾柴火焰高，我们欢迎你参与到界面管理工作中来。

提出建议、意见

我们欢迎你在萌娘百科技术实现讨论版提出建议、意见，我们会审慎考虑可行性和成本等因素后作出决定。

提交贡献

提交贡献的原因有很多，可能是发现了 typo，可能你写成了一个小工具，不论如何我们都欢迎你来提交贡献。

但首先，最重要的一点是：务必阅读并遵守 CONTRIBUTING.md，否则你的贡献有可能被拒绝。

其次，由于需要确保（虽然永远也不可能出现的）将小工具迁移到 Gadget 名字空间的情况的兼容性，文件名对应了萌娘百科上对应页面的页面名，从而包含了 :，而这导致了本仓库无法在 Windows 上克隆。

所以我们建议你通过以下方式提交贡献：

使用 Linux on Windows with WSL； 使用 Linux 系统（可以是远程服务器、本地虚拟机、本地 Docker 容器等）； 使用 macOS 系统； 使用 GitHub Codespaces（对个人用户有免费额度）。

然后，我们建议你使用 Visual Studio Code，本仓库专为 VSCode 配置。我们也建议你搭配以下 VSCode 扩展结合本仓库提供的配置以优化体验：

Conventional Commits（约定式提交）：Conventional Commits 扩展； eslint：ESLint 扩展； stylelint：Stylelint 扩展； 远程开发： 在 Linux on Windows with WSL 里：Remote - WSL 扩展； 在运行 Linux 的本地 Docker 容器里：Remote - Containers 扩展； 在运行 Linux 的本地虚拟机或远程服务器里：Remote - SSH 扩展和 Remote - SSH: Editing Configuration Files 扩展。