企业官网建设流程全解析

• UI组件
• 前端

本指南以 react-modal 仓库的 docs/contributing/index.md 与 docs/contributing/development.md 为核心，系统讲解如何为这个可访问性（Accessible）React 弹窗组件贡献代码：从提交信息（Commit Subject）的规范化前缀、API 变更的升级路径要求，到本地开发、测试、Lint 的完整命令，再到基于 Makefile 的构建、文档与 npm 发布流水线。读完本文，你将掌握 react-modal 贡献者视角下的完整工作流，并能对照源码理解CHANGELOG.md自动生成、版本号同步、gh-pages 文档发布等底层机制。

Commit Subjects：为自动生成的 Changelog 而写

react-modal 要求贡献者在提交信息中使用语义化前缀，这并非形式主义——仓库的发布脚本 scripts/changelog.py 会直接扫描 Git 历史来生成CHANGELOG.md，因此提交主题的规范性直接决定了发布记录的可读性。

何时必须使用前缀

如果你的补丁改变了 API 或修复了 Bug，请在提交主题（subject）中使用以下前缀之一：

• [fixed] ...—— 修复 Bug
• [changed] ...—— 行为/API 发生变更
• [added] ...—— 新增功能或 API
• [removed] ...—— 移除功能或 API

这能确保提交主题进入自动生成的 changelog。反之，如果你的变更既没有修 Bug、也没有改变公开 API，就不要使用这些标签，避免污染发布记录。

从源码看，scripts/changelog.py 在汇总日志时会过滤掉以Release或release开头的提交行，其余提交以- hash subject的格式逐条写入对应版本区间；结合LOG_ENTRY模板（version + date + dashes + entries），可以确认 changelog 的每个版本条目就是由这些前缀标签的提交构成的。

前缀的配套纪律

• [changed]或[removed]属于破坏性变更，必须在提交信息中附带上升级路径（upgrade path）与示例代码，帮助下游使用者平滑迁移。如果觉得"没有合理的升级路径可写"，那么本身就说明不应该使用[changed]/[removed]。
• 带有[changed]、[added]、[removed]前缀的提交，必须由另一位协作者（collaborator）评审通过后方可合并。

这条规则与 CONTRIBUTING.md 中"补丁只有在 GitHub 上有对应 issue 才会被接受"的要求共同构成了 react-modal 的变更管理底线：先有 issue 讨论，再有带规范的提交，最后进入可追溯的发布记录。

Docs：代码与文档必须保持同步

贡献者被明确要求：任何 API 变更都要同步更新 README。这条约定保证了README.md始终反映当前组件行为，避免"代码是新版、文档是旧版"的常见断层。

仓库的文档体系以 mkdocs 驱动（见 mkdocs.yml），导航中包含 Accessibility、Styles、Examples、Testing、Contributing 等章节，文档源码全部位于 docs/ 目录，并会被发布到 gh-pages 分支。因此在修改 API 时，除了 README，还应审视 docs/ 下对应章节是否需要同步更新（例如docs/accessibility/index.md、docs/examples/*.md、docs/styles/*.md）。

Development：本地开发与测试命令

react-modal 的日常开发围绕三个核心命令展开（对应 package.json 中的 scripts 定义）：

示例开发服务器

npm start通过 scripts/webpack.config.js 启动 webpack-dev-server，将examples/作为内容根目录，并把react-modal通过 alias 指向../src（见 scripts/defaultConfig.js）。这意味着示例页面直接引用源码而非构建产物，改动src/即可热更新，无需先构建。仓库自带的示例覆盖了基础用法（examples/basic/simple_usage/index.js）、多弹窗、嵌套弹窗、表单、react-router 集成以及 Web Components 变体（examples/wc/app.js）等场景，是快速验证改动效果的理想入口。

测试框架与监听模式

npm test由 karma.conf.js 驱动，采用 mocha 框架，测试入口为 specs/index.js，源码目录./src/**/*.js会走 coverage 预处理并生成覆盖率报告。关键配置是：

autoWatch: true, singleRun: (process.env.CONTINUOUS_INTEGRATION)

即默认情况下 karma 处于监听（watch）模式，源码或测试文件一保存就自动重跑相关用例——这与文档中scripts/test"保持 karma 运行并监听变化"的描述在行为上是一致的（原文档提到的scripts/test脚本在当前仓库中已不存在，实际由 karma 的autoWatch: true承担该职责）。而 CI 环境（设置CONTINUOUS_INTEGRATION环境变量）下会切换到 Firefox 浏览器并执行单次运行（singleRun），覆盖率报告输出lcovonly格式。

仓库的测试资产非常完整，五个 spec 文件分别覆盖事件（specs/Modal.events.spec.js）、辅助方法（specs/Modal.helpers.spec.js）、核心渲染（specs/Modal.spec.js）、样式（specs/Modal.style.spec.js）与可测试性（specs/Modal.testability.spec.js），新增功能时建议参照这些文件的既有模式补充用例。

环境注意事项

CONTRIBUTING.md 记录了一个已知坑：如果安装或构建时遇到Error: error:0308010C:digital envelope routines::unsupported（Node 的 OpenSSL 错误），说明当前 Node 版本过高（≥ 18 的 OpenSSL 3 与仓库使用的旧版构建链不兼容），请改用 Node 版本 < 18。这在用较新系统环境开发时尤其常见。

Build：不要提交构建产物

文档明确要求：不要把你的构建输出提交进仓库。react-modal 只在发布时执行构建，日常开发通常无需构建（除非你在修复全局构建相关的问题）。

从 Makefile 可以看到构建分为两步：

compile: $(BABEL) src --out-dir lib build: compile npx webpack --config ./scripts/webpack.dist.config.js

• compile：用 Babel 把 src/ 编译到lib/（对应 package.json 的main与module字段）；
• build：再用 webpack（scripts/webpack.dist.config.js）打包出dist产物。

这些产物由维护者统一在发布时产出，协作者只需提交源码，这保证了仓库主干的纯净、避免合并冲突。

Make 流水线：从依赖安装到发布的一站式清单

Makefile 是 react-modal 构建与发布的"总调度器"，文档 docs/contributing/development.md 将其描述为一张面向未来版本的发布检查清单，负责同步CHANGELOG.md、package.json、bower.json等全部发布要素。

环境自检

克隆仓库后，可以先运行make info查看当前node、npm/yarn、jq的版本信息（对应 Makefile 中的info目标）。Makefile 还支持通过PKM变量在 npm 与 yarn 之间切换包管理器。

常用命令速查

结合文档与 Makefile 源码，常用的 npm/yarn 与 make 命令如下：

发布流水线的源码级拆解

make publish的完整链路为（Makefile）：

check-working-tree → pre-publish(clean) → pre-build(deps + tests-single-run + build) → publish-version(release-commit + release-tag + push + npm publish) → publish-finished(clean)

其中几个关键环节值得贡献者留意：

1. 工作区检查：scripts/repo_status 会先检查git status是否干净——有未提交改动会停下发布并询问是否继续，从源头避免把半成品发布出去。
2. 版本号同步：scripts/version 脚本同时用jq更新package.json与bower.json的version字段，并校验新标签是否已存在。这也是文档强调要维护bower.json的原因（bower.json 中的版本需要与 npm 包保持同步）。
3. Changelog 自动生成：changelog目标执行python ./scripts/changelog.py -a <version> > CHANGELOG.md。该脚本依赖 Python 3（注释明确说明 Python 3 才支持%z时区格式），通过git log遍历版本标签区间，过滤掉Release提交后按前缀标签生成条目，最终输出完整的新版 CHANGELOG.md。注意：脚本头部硬编码了作者本机的 site-packages 路径，属于历史遗留，运行前需确保本机安装semver依赖。
4. 提交与打标签：release-commit依次完成空提交、更新 package.json 版本、重写 changelog、git commit --amend；release-tag则用 changelog 摘要创建vX.Y.Z标签；最后推送分支与标签并执行npm publish。

文档发布流程

make publish-docs负责把 mkdocs 构建结果发布到gh-pages分支（Makefile）：

clean → pre-publish-docs(clean-docs + init-docs-repo + deps-docs) → build-docs(mkdocs build) → 在 _book 中初始化 git 仓库 → 切到 gh-pages → touch .nojekyll → 强推

build-docs还会用pygmentize生成代码高亮样式 docs/pygments.css。由于是--force推送，gh-pages 分支始终保持为最新构建产物，配合 mkdocs.yml 中的site_dir: _book配置完成整条文档发布链路。

小结：一条完整的贡献路径

综合本文内容，一个合格的 react-modal 贡献流程可以概括为：

1. 先在 GitHub 上创建/认领对应 issue，与维护者讨论方案（CONTRIBUTING.md）；
2. 本地make deps安装依赖，npm start起示例服务器验证效果；
3. 编写代码并补充/调整 specs/ 下的测试用例，npm test（karma 监听模式）持续验证，npm run lint保证代码风格；
4. 若变更 API 或修复 Bug，提交信息使用[fixed]/[changed]/[added]/[removed]前缀，破坏性变更附上升级路径示例，并同步更新 README 与 docs/ 相关章节；
5. 绝不提交lib/构建产物，保持工作区干净后推送，等待另一位协作者评审。

这条路径既保证了组件库的可访问性质量（核心源码见 src/components/Modal.js 与 src/components/ModalPortal.js），也通过规范化的提交与自动化发布脚本，让每个版本变更都能在 CHANGELOG.md 中被清晰追溯。

• UI组件
• 前端