• 前端
• 静态站点

本文以 hexo-theme-icarus 仓库的 CONTRIBUTING.md 为骨架，逐条拆解该项目面向外部贡献者制定的开发协作规范：代码风格与 lint 自动化、基于 SemVer 的版本发布约束、一套与仓库目录结构精确对应的 commit message scope 体系，以及从 Fork 到 PR 合入的完整提交流程。读者读完可以照着规范直接为 Icarus 提交符合项目要求的代码、提交信息与合并请求，也能借此理解一个成熟 Hexo 主题如何用工程化手段管理插件、国际化与版本迁移。

为什么需要一份贡献指南

hexo-theme-icarus 是一个"简单、精致且现代"的 Hexo 主题（见 README.md），其代码库同时包含 Node.js 侧的配置检查与迁移逻辑（include/）、Inferno.js 渲染模板（layout/）、Stylus 样式（source/css/）以及 17 个语言的翻译文件（languages/）。代码横跨多种语言与技术栈，外部贡献者若各写各的风格，很容易让合并、维护和版本发布陷入混乱。CONTRIBUTING.md 用短短 40 行规定了四条硬性约束：代码风格、版本号、提交信息格式、提交流程。下面逐条结合仓库源码展开。

一、代码风格：ESLint 与npm run lint

原文档要求所有贡献者以仓库根目录的.eslintrc.json为唯一风格基准，并用npm run lint或yarn lint自动修复格式问题。这套 lint 配置在仓库中确实真实存在且有明确的执行入口。

lint 命令从哪来

package.json 的scripts字段定义：

"scripts": { "lint": "eslint --ext .js --ext .jsx --ext .json ." }

即对当前目录下所有.js、.jsx、.json文件执行 ESLint 检查，开发依赖中锁定了eslint ^8.56.0、eslint-config-hexo ^5.0.0、eslint-plugin-react ^7.33.2、eslint-plugin-json ^3.1.0等工具链。贡献者在提交前运行该命令，即可在本地发现并修复格式问题。

.eslintrc.json的规则要点

.eslintrc.json 的配置体现了 Icarus 的具体代码风格约束：

• 继承三个规则集：hexo（Hexo 官方 ESLint 配置）、plugin:react/recommended（React/Inferno JSX 推荐规则）、plugin:json/recommended（JSON 文件校验）。
• 缩进：强制 4 空格缩进，SwitchCase额外缩进 1 级：

"indent": ["error", 4, { "SwitchCase": 1 }]

• JSX 特有规则：由于模板使用 Inferno（类 React 的 JSX 语法），配置了react/jsx-uses-vars、react/jsx-no-target-blank（并允许allowReferrer: true），同时关闭了react/react-in-jsx-scope、react/prop-types、react/display-name、react/jsx-key等对 Inferno 场景不适用或过于严苛的规则。
• HTML 属性兼容：react/no-unknown-property允许class、onclick、onload、onsubmit、crossorigin等原生 HTML 属性名（Inferno 模板中直接书写 DOM 属性，而非 React 的className）。
• 解析环境：parserOptions开启jsx: true、sourceType: "module"、ecmaVersion: "latest"。

值得注意的还有两处环境定制：

• .eslintignore 只有一行node_modules/，即 lint 会覆盖除依赖目录外的全部源码。
• source/js/.eslintrc.json 继承根配置并声明env为browser: true、jquery: true、node: false——因为 source/js/ 下的animation.js、back_to_top.js、main.js、pjax.js运行在浏览器端（部分依赖 jQuery），与 Node.js 侧的scripts/index.js、include/ 运行环境截然不同。

实践建议：本地克隆后先在站点根目录（或主题目录）执行npm install，再运行npm run lint，把输出中的error级别问题全部清零后再发起 PR；修复命令可配合eslint --fix使用。

二、版本管理：SemVer 与配置版本迁移机制

原文档要求项目采用 SemVer（语义化版本控制，即主版本号.次版本号.修订号的 MAJOR.MINOR.PATCH 三段式版本号）进行版本管理，并明确规定"任何代码变更都不得以已有版本号发布"。

仓库中有多处证据印证这套版本策略：

• package.json 当前版本为6.1.1（主版本 6、次版本 1、修订 1），符合三段式结构。
• 主题配置本身也带版本号：include/schema/config.json 中version字段的默认值为"5.1.0"，与当前主题版本（6.x）解耦，用于标识配置文件格式的演进。
• 配置迁移代码完整实现了"升级版本 → 迁移字段"的机制：include/config.js 在hexo生成站点时检测配置version，若低于最新版本则先备份（按文件内容 MD5 命名备份文件），再调用迁移器逐级升级。迁移器定义在 include/migration/head.js，它逐级引用 include/migration/v5_v5.1.js 等迁移脚本——每个脚本以Migration子类形式声明super('目标版本', null)并实现upgrade(config)，例如 v5_v5.1 负责把 Waline 评论插件的visitor、uploadImage、highlight、math四个选项分别重命名为pageview、image_uploader、highlighter、tex_renderer。

这套"配置随版本演进、旧配置自动迁移"的设计，正是 SemVer 在 Icarus 中的具体落地：主题升级主版本时，配置文件的 schema 会同步演进，而迁移器保证了旧站点配置平滑升级，而不是直接报错或静默丢失。

贡献者须知：如果你的 PR 涉及配置项新增、重命名或删除，请在 PR 描述中说明需要增加的迁移逻辑（参考 include/migration/ 现有脚本的写法），否则升级路径会被破坏。

三、提交信息格式：type(scope) 与九大 scope 体系

原文档要求 commit message 遵循"Bluejava commit message format"（一种type(scope): subject式的结构化提交信息约定），并列出了项目支持的全部 scope。这是 CONTRIBUTING.md 中信息密度最高的一节，因为scope 与仓库目录结构一一对应，是理解 Icarus 模块划分的最佳入口。

支持的 scope 与代码模块映射

从上表可以直观看出：Icarus 的插件体系（评论、分享、打赏、搜索、侧栏组件）在源码上拥有完全对称的目录结构——每种插件都有独立的layout模板目录、JSON Schema 配置目录与公共 schema 引用。贡献者只需按 scope 即可定位修改范围。

提交信息写法示例

结合上述 scope 与 Bluejava 式type(scope): subject格式，实际提交可写成：

feat(comment): add support for Waline pageview option fix(search): correct Baidu search result page link refactor(core): move config validation into include/config.js docs(i18n): add zh-CN translation for the new widget style(plugin): reformat pjax script to pass eslint

原文档特别强调：无法清晰归入某个 scope 的改动，使用*或留空，不要硬套。

四、提交变更：Fork-PR 工作流与评审约定

原文档最后给出标准的开源协作流程，共 4 步：

1. Fork 并本地验证：Fork 本仓库后做出修改，必须把改动跑在真实的 Hexo 站点上验证是否有破坏（例如用hexo clean && hexo generate && hexo server本地预览），并运行npm run lint/yarn lint修复所有格式问题。
2. 提交 Pull Request：确保已遵循前述代码风格、版本与提交信息约定，然后向主仓库发起 PR。
3. 等待评审：维护者会定期评审 PR，并提出问题或需要修改的地方；按反馈修改后才能合并。
4. 两周响应窗口：维护者期望贡献者在两周内对评审意见作出回应；若两周内无任何活动，PR 可能被关闭。

这套流程与仓库的工程化设计是配合的：由于 scripts/index.js 在hexo启动时会依次执行依赖检查（include/dependency.js 会用semver校验hexo-component-inferno等关键依赖版本，缺失或版本不符会直接报错并提示npm install --save ...）、配置检查与迁移（include/config.js）、扩展注册（include/register.js），贡献者本地跑一次hexo命令就能暴露大多数环境问题；而 CI 侧则会通过 lint 拦截格式错误。因此"先跑真实站点 + 先过 lint"是 PR 能否快速被合并的关键前提。

五、给贡献者的快速自查清单

综合全文，向 Icarus 提交代码前请依次核对：

• 代码遵循 .eslintrc.json（4 空格缩进、JSX 规则、JSON 校验），npm run lint无 error；
• 若新增/修改插件，同时更新对应的 layout/ 模板、include/schema/ Schema 与必要样式；
• 若涉及配置项变更，同步考虑 include/migration/ 中的版本迁移脚本；
• 新增语言文本时，同步维护 languages/ 下的多语言翻译文件（对应i18nscope）；
• commit message 采用type(scope): subject格式，scope 从 core/comment/share/donate/search/widget/plugin/i18n/test/build 中选择，归属不明时用*；
• 不修改或复用已有版本号发布改动；
• 在真实 Hexo 站点上验证无破坏后，提交 PR 并在两周内响应评审意见。

按这套规范行事，你的贡献就能顺畅地融入这个拥有完整插件体系、多语言支持与配置自动迁移能力的现代 Hexo 主题。

• 前端
• 静态站点