DevDocs 如何把已有文档源（documentation）更新到最新版本并提交 PR？

DevDocs（API Documentation Browser）中每一套文档都由一个 Ruby scraper 抓取生成。源站点的版本和页面结构会随时间变化， scraper 需要跟进最新版本并调整过滤逻辑。这篇文章的目标是：把一套已有文档更新到最新版本，在本地验证通过后按项目要求提交 PR。流程依据 CONTRIBUTING.md 中的 "Updating existing documentations" 清单，配置细节参考 Scraper Reference。

准备本地环境

更新文档需要在本地 clone 的仓库中运行 scraper，而不是在 devdocs.io 网页上操作。README 给出的环境要求：

• Ruby 4.0.6（在 Gemfile 中定义）、libcurl，以及一个 ExecJS 支持的 JavaScript 运行时（OS X 和 Windows 自带；Linux 上可用 Node.js）。Arch Linux 用户可用 pacman -S ruby ruby-bundler ruby-erb ruby-irb 安装这些组件；
• 若系统安装了多个 Ruby 版本，所有命令要通过 bundle exec 运行。

git clone https://github.com/freeCodeCamp/devdocs.git && cd devdocs
gem install bundler
bundle install

确认文档确实过时

运行 thor updates:check <doc> 检查指定文档（如 thor updates:check rails），它会把 scraper 当前记录的版本与最新版本对比，以表格形式输出 Documentation、Scraper version、Latest version 三列，过时的文档会被归入 "Outdated" 组。判断过时的依据是 scraper 的 get_latest_version 方法：Scraper Reference 的 Keeping scrapers up-to-date 一节说明，若定义了 self.release，该方法应返回文档的最新版本，并提供了 get_latest_github_release、get_npm_version 等工具方法。这些检查结果还会定期汇总到仓库的 "Documentation versions report" issue 中。CONTRIBUTING 提示：如果该报告错误地显示某文档仍是最新，应开 issue 或 PR 来修正 get_latest_version 的实现。

一个版本兼容性细节：lib/docs/core/doc.rb 中的注释指出 "Patch updates are ignored because there are usually little to no documentation changes in bug-fix-only releases"，即补丁版本（patch）差异不会被视为过时。

更新 scraper 文件

按 CONTRIBUTING 的步骤 1–5，在 lib/docs/scrapers/ 下找到对应 scraper：

1. 修改 scraper 文件中的版本/发布说明。release 属性记录 scraper 上次运行时的软件版本，仅信息性用途、不影响抓取行为，但仍需同步更新；
2. 检查 license 是否仍然正确，如有变化更新 options[:attribution]；
3. 如果该文档使用自定义图标，确认 public/icons/*your_scraper_name*/ 下的图标是最新的；若新图标来源与 SOURCE 文件中记录的地址不同，要把旧链接替换为新链接；
4. 如果定义了 self.links，检查其中的 URL 是否仍然有效；
5. 如果 scraper 继承自 FileScraper（从本地文件系统读取源文件而非 HTTP 抓取），先按 file-scrapers.md 的说明获取新的源材料。

生成文档并本地验证

对每个要更新的版本执行生成命令，格式为 <doc@version>（slug + @ + 版本，例如 rails@5.2 这类写法）：

thor docs:generate <doc@version>

CONTRIBUTING 步骤 7 给出了验证要求：确认 thor docs:generate 没有报错，且文档仍然工作正常；本地确认一切正常、条目的归类（categorization）仍然合理。文档明确提示，更新常常需要修改 scraper 或其 filters 的代码，以适应源网站的新标记结构或为新增条目归类。如果一次更新了多个版本，对每个版本重复生成与验证。

验证方式与新增文档相同（adding-docs.md）：启动服务器（rackup），打开 http://localhost:9292，启用该文档，实际浏览确认页面效果。

注意响应缓存：UrlScraper 会把抓取到的响应缓存到 tmp/cache/[slug]，且缓存永不过期。如果源站内容已变但生成结果仍是旧的，需要先运行 thor docs:clean 清空缓存（该命令同时会删除已打包的文档文件，见 maintainers.md），再重新生成。

提交 PR

生成并验证完成后创建 PR，并填写 PR 模板 中 Section B（"Updating an existing documentation to its latest version"）的清单，删除其他不适用的 Section：

• [ ] Updated the versions and releases in the scraper file
• [ ] Ensured the license is up-to-date
• [ ] 如文档有自定义图标：确认 public/icons/*your_scraper_name*/ 中的图标与 SOURCE 文件均为最新
• [ ] 如定义了 self.links：确认其中 URL 为最新
• [ ] 已本地测试：scraper 无错误运行、抓取的文档与 DevDocs 其他文档观感一致、条目归类仍然合理

CONTRIBUTING 明确警告：缺少 Section B 清单的更新 PR 可能不经过 review 直接关闭。尚未完成全部步骤时可先创建 draft PR。

提交前还要注意一条仓库约束（maintainers.md）：public/docs/docs.json 永远不要提交，该文件只反映本地下载/生成过哪些文档，在全新 clone 中应当为空。

PR 被合并后，推送到 main 分支会触发 GitHub Action 先运行测试，测试通过后自动部署 Heroku 应用。对部署了文档更新的场景，maintainers.md 给出的生产验证方式是：等待 service worker 缓存完新资产（需要几秒），出现 "DevDocs has been updated" 通知后刷新页面即可看到更新后的文档。另外，维护者流程要求含文档更新/新增的 PR 在合并前需由维护者用 thor docs:upload 上传文档文件，这一环节由维护者完成，贡献者无需执行。