为 Ruby 标准库stdlib贡献代码镜像仓库、构建与测试完整指南【免费下载链接】rubyThe Ruby Programming Language项目地址: https://gitcode.com/GitHub_Trending/ru/ruby本指南基于 doc/contributing/making_changes_to_stdlibs.md 展开面向希望为 Ruby 标准库提交代码的开发者。你将理解 Ruby 仓库中lib/目录“镜像自独立仓库”的协作模式掌握在独立标准库仓库中安装依赖、编译 C 扩展、运行全部或单个测试用例的完整流程并能借助本仓库的同步脚本与清单文件深入理解镜像机制。核心前提标准库代码不直接在 ruby/ruby 中修改Ruby 仓库的 lib 目录中几乎所有内容都是从独立的仓库镜像mirror进来的而不是在 Ruby 主仓库中直接维护。这意味着若你想为标准库提交贡献bug 修复、新特性、文档改进不要在 Ruby 主仓库的lib/下直接改动正确做法是到该库对应的独立仓库提交 Pull Request改动会被自动镜像回 Ruby 仓库。文档中的典型例子是 ERBERB 维护在独立的 ruby/erb 目录。从当前仓库结构看这一结论可以得到直接印证lib/erb下存在 compiler.rb、def_method.rb、util.rb、version.rb 等源文件以及 erb.gemspec其 gemspec 就放在lib/erb/内部这正是“独立 gem 以自身仓库为家、以镜像形式进入主仓库”的布局特征。谁在维护维护者清单在动手提交之前建议先确认目标库的维护者并在 PR 或讨论中 相关维护者。维护者清单位于 doc/maintainers.md每个库都会列出负责人与联系方式遵循清单能显著提高贡献被合并的效率。从仓库源码看镜像机制sync_default_gems.rb虽然对外贡献发生在独立仓库但理解“镜像”是如何发生的对排查“为什么主仓库里这个文件长这样”非常有帮助。Ruby 仓库中的 tool/sync_default_gems.rb 就是负责把上游仓库同步回主仓库的脚本。该脚本的核心数据结构是RepositoryData.define(:upstream, :branch, :mappings, :exclude)其中upstream上游仓库的owner/repo标识branch同步时使用的分支mappings[上游路径, Ruby 仓库路径]的映射列表同步时把上游文件按映射重写路径exclude需要排除的文件模式例如脚本默认排除.a、.bundle、.dll、.so等编译产物见excluded?方法。脚本内置了一张大表REPOSITORIES几乎覆盖了所有标准库。例如 ERB 的配置为erb: repo(ruby/erb, [ [ext/erb, ext/erb], [lib/erb, lib/erb], [lib/erb.rb, lib/erb.rb], [test/erb, test/erb], [erb.gemspec, lib/erb/erb.gemspec], [libexec/erb, libexec/erb], ]),这段配置清晰地表明上游ruby/erb仓库的lib/erb、test/erb等路径会被原样映射进 Ruby 仓库而erb.gemspec会被放到lib/erb/下——这正解释了上面观察到的仓库布局。该脚本支持多种同步模式通过命令行参数选择# 通过 git clone cp 导入全部默认 gem丢失 git 提交历史 ruby tool/sync_default_gems.rb all # 导入所有默认 gem 的最新发布版本 ruby tool/sync_default_gems.rb all release # 只导入某个 gem如 rubygems ruby tool/sync_default_gems.rb rubygems # 从上游仓库挑选单个提交 ruby tool/sync_default_gems.rb rubygems 97e9768612 # 挑选一个提交区间 ruby tool/sync_default_gems.rb rubygems 97e9768612..9e53702832 # 挑选自上次挑选以来的所有提交-a 自动模式 ruby tool/sync_default_gems.rb -a rubygems # 更新默认 gem 的本地克隆仓库 ruby tool/sync_default_gems.rb up # 列出已知库支持正则过滤 ruby tool/sync_default_gems.rb list ruby tool/sync_default_gems.rb list read对于贡献者而言这份脚本的价值在于你可以通过 tool/sync_default_gems.rb 中的 REPOSITORIES 表 查清“某个库的上游仓库地址、同步分支与路径映射”从而确认该去哪里提交 PR。默认 gem 与捆绑 gemgems/bundled_gems 清单除了lib/下的标准库Ruby 还捆绑了一批随发行版一起发布的 gem。仓库根目录的 gems/bundled_gems 文件以如下格式维护这份清单# gem-name version repository-url [revision] # # - gem-name: gem name to bundle # - version: released version to bundle # - repository-url: URL from where clone for test # - revision: revision in repository-url to test # if revision is not given, vversion or version will be used.实际条目示例minitest 6.0.6 https://github.com/minitest/minitest test-unit 3.7.8 https://github.com/test-unit/test-unit rexml 3.4.4 https://github.com/ruby/rexml net-imap 0.6.6 https://github.com/ruby/net-imap irb 1.18.0 https://github.com/ruby/irb ac42eaaa88e6399384c1a56cc948c4b2528a9cc2 rdoc 8.0.0 https://github.com/ruby/rdoc a9ebd59d3a49b1e929ae8658f84d3a29a360e10e bigdecimal 4.1.2 https://github.com/ruby/bigdecimal csv 3.3.6 https://github.com/ruby/csv logger 1.7.0 https://github.com/ruby/logger该清单由 tool/fetch-bundled_gems.rb 消费脚本按行读取清单对每个 gem 执行git clone --depth1然后 checkout 到发布 tag优先v{version}否则{version}若指定了 revision 则直接 checkout 该 commit。这些克隆出来的源码用于在 Ruby 主仓库环境下测试捆绑 gem。在标准库仓库中构建拿到某个标准库独立仓库的代码后或为贡献准备的本地克隆第一步是安装其依赖bundle install这一步会读取仓库根目录的Gemfile与 gemspec把库自身运行与测试所需的 gem 依赖安装到本地。带 C 扩展的库需要编译如果该库带有/ext目录说明它包含需要编译的 C 文件例如性能关键路径的扩展必须先编译bundle exec rake compile为什么需要这一步以 ERB 的 C 扩展为例仓库中的 ext/erb/escape 目录包含 escape.c 与 extconf.rb。其extconf.rb会做一系列编译前探测检查rb_ext_ractor_safe函数与 Ruby Ractor 安全标记相关在非 JRuby/TruffleRuby 环境下探测当前 CPU 架构arm/aarch64 用 NEONx86_64 用 SSE2尝试编译一段 SIMD 小程序成功则定义ERB_ENABLE_SIMD宏以启用向量化转义路径可通过环境变量ERB_DISABLE_SIMD关闭该探测最终通过create_makefile erb/escape生成 Makefile。这段逻辑说明rake compile对这类库不是可选项而是让 Ruby 代码调用到本地优化实现如ERB::Escape的必要前提。同理ext/date、ext/stringio、ext/strscan 等目录都遵循“/ext目录 extconf.rb 编译”的模式。运行测试所有标准库统一使用 test-unit 作为测试框架本仓库 gems/bundled_gems 中即可找到test-unit 3.7.8的捆绑条目。测试目录约定为仓库内的test/测试文件命名如test/test_foo.rb。运行全部测试bundle exec rake test只跑单个测试文件bundle exec rake test TESTtest/test_foo.rb通过TEST变量指定目标文件适合在迭代某个模块时快速反馈。只跑单个测试用例bundle exec rake test TESTtest/test_foo.rb TESTOPTS--name/test_mytest/TESTOPTS透传给 test-unit 的命令行选项--name/正则/用正则匹配测试方法名test_mytest从而只执行指定的测试方法。深度印证Ruby 主仓库如何批量测试这些库如果你改动的库恰好也是捆绑 gem如 rexml、irb、csv 等Ruby 主仓库还提供了整体验证手段。脚本 tool/test-bundled-gems.rb 会遍历 gems/bundled_gems 中每个 gem其源码由tool/fetch-bundled_gems.rb克隆到gems/src/gem在各自目录下以本仓库构建出的ruby执行rake test并做并行调度、超时控制默认首轮 10 分钟与结果汇总。该脚本还体现了“允许失败”的边界处理通过DEFAULT_ALLOWED_FAILURES与TEST_BUNDLED_GEMS_ALLOW_FAILURES环境变量可以容忍特定平台下的已知失败如 Windows 下的 debug/irb/csv、缺少diff命令时的 minitest失败信息中会明确打印 “Ignoring test failures for ... due to ...”。常用调用方式# 测试全部捆绑 gem make test-bundled-gems # 只测试指定 gem make test-bundled-gems BUNDLED_GEMSgem1,gem2,gem3贡献流程总结综合本文向 Ruby 标准库提交贡献的完整路径是定位上游仓库通过 tool/sync_default_gems.rb 的 REPOSITORIES 表 或 gems/bundled_gems 清单确认目标库的独立仓库地址与版本在独立仓库开发clone 上游仓库先bundle install若库带/ext目录则再执行bundle exec rake compile本地验证bundle exec rake test跑全量或用TEST、TESTOPTS--name/.../精准回归提交 PR 到独立仓库改动会由 Ruby 团队的镜像流程tool/sync_default_gems.rb自动进入 Ruby 主仓库无需也不应直接在 lib 目录下手动改文件必要时刻参考维护者doc/maintainers.md 中的清单可帮你找到合适的 reviewer。牢记“镜像协作”这一核心前提你就能避免在错误的位置修改代码从而以正确的姿势参与 Ruby 标准库的建设。【免费下载链接】rubyThe Ruby Programming Language项目地址: https://gitcode.com/GitHub_Trending/ru/ruby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 为 Ruby 标准库（stdlib）贡献代码：镜像仓库、构建与测试完整指南
为 Ruby 标准库stdlib贡献代码镜像仓库、构建与测试完整指南【免费下载链接】rubyThe Ruby Programming Language项目地址: https://gitcode.com/GitHub_Trending/ru/ruby本指南基于 doc/contributing/making_changes_to_stdlibs.md 展开面向希望为 Ruby 标准库提交代码的开发者。你将理解 Ruby 仓库中lib/目录“镜像自独立仓库”的协作模式掌握在独立标准库仓库中安装依赖、编译 C 扩展、运行全部或单个测试用例的完整流程并能借助本仓库的同步脚本与清单文件深入理解镜像机制。核心前提标准库代码不直接在 ruby/ruby 中修改Ruby 仓库的 lib 目录中几乎所有内容都是从独立的仓库镜像mirror进来的而不是在 Ruby 主仓库中直接维护。这意味着若你想为标准库提交贡献bug 修复、新特性、文档改进不要在 Ruby 主仓库的lib/下直接改动正确做法是到该库对应的独立仓库提交 Pull Request改动会被自动镜像回 Ruby 仓库。文档中的典型例子是 ERBERB 维护在独立的 ruby/erb 目录。从当前仓库结构看这一结论可以得到直接印证lib/erb下存在 compiler.rb、def_method.rb、util.rb、version.rb 等源文件以及 erb.gemspec其 gemspec 就放在lib/erb/内部这正是“独立 gem 以自身仓库为家、以镜像形式进入主仓库”的布局特征。谁在维护维护者清单在动手提交之前建议先确认目标库的维护者并在 PR 或讨论中 相关维护者。维护者清单位于 doc/maintainers.md每个库都会列出负责人与联系方式遵循清单能显著提高贡献被合并的效率。从仓库源码看镜像机制sync_default_gems.rb虽然对外贡献发生在独立仓库但理解“镜像”是如何发生的对排查“为什么主仓库里这个文件长这样”非常有帮助。Ruby 仓库中的 tool/sync_default_gems.rb 就是负责把上游仓库同步回主仓库的脚本。该脚本的核心数据结构是RepositoryData.define(:upstream, :branch, :mappings, :exclude)其中upstream上游仓库的owner/repo标识branch同步时使用的分支mappings[上游路径, Ruby 仓库路径]的映射列表同步时把上游文件按映射重写路径exclude需要排除的文件模式例如脚本默认排除.a、.bundle、.dll、.so等编译产物见excluded?方法。脚本内置了一张大表REPOSITORIES几乎覆盖了所有标准库。例如 ERB 的配置为erb: repo(ruby/erb, [ [ext/erb, ext/erb], [lib/erb, lib/erb], [lib/erb.rb, lib/erb.rb], [test/erb, test/erb], [erb.gemspec, lib/erb/erb.gemspec], [libexec/erb, libexec/erb], ]),这段配置清晰地表明上游ruby/erb仓库的lib/erb、test/erb等路径会被原样映射进 Ruby 仓库而erb.gemspec会被放到lib/erb/下——这正解释了上面观察到的仓库布局。该脚本支持多种同步模式通过命令行参数选择# 通过 git clone cp 导入全部默认 gem丢失 git 提交历史 ruby tool/sync_default_gems.rb all # 导入所有默认 gem 的最新发布版本 ruby tool/sync_default_gems.rb all release # 只导入某个 gem如 rubygems ruby tool/sync_default_gems.rb rubygems # 从上游仓库挑选单个提交 ruby tool/sync_default_gems.rb rubygems 97e9768612 # 挑选一个提交区间 ruby tool/sync_default_gems.rb rubygems 97e9768612..9e53702832 # 挑选自上次挑选以来的所有提交-a 自动模式 ruby tool/sync_default_gems.rb -a rubygems # 更新默认 gem 的本地克隆仓库 ruby tool/sync_default_gems.rb up # 列出已知库支持正则过滤 ruby tool/sync_default_gems.rb list ruby tool/sync_default_gems.rb list read对于贡献者而言这份脚本的价值在于你可以通过 tool/sync_default_gems.rb 中的 REPOSITORIES 表 查清“某个库的上游仓库地址、同步分支与路径映射”从而确认该去哪里提交 PR。默认 gem 与捆绑 gemgems/bundled_gems 清单除了lib/下的标准库Ruby 还捆绑了一批随发行版一起发布的 gem。仓库根目录的 gems/bundled_gems 文件以如下格式维护这份清单# gem-name version repository-url [revision] # # - gem-name: gem name to bundle # - version: released version to bundle # - repository-url: URL from where clone for test # - revision: revision in repository-url to test # if revision is not given, vversion or version will be used.实际条目示例minitest 6.0.6 https://github.com/minitest/minitest test-unit 3.7.8 https://github.com/test-unit/test-unit rexml 3.4.4 https://github.com/ruby/rexml net-imap 0.6.6 https://github.com/ruby/net-imap irb 1.18.0 https://github.com/ruby/irb ac42eaaa88e6399384c1a56cc948c4b2528a9cc2 rdoc 8.0.0 https://github.com/ruby/rdoc a9ebd59d3a49b1e929ae8658f84d3a29a360e10e bigdecimal 4.1.2 https://github.com/ruby/bigdecimal csv 3.3.6 https://github.com/ruby/csv logger 1.7.0 https://github.com/ruby/logger该清单由 tool/fetch-bundled_gems.rb 消费脚本按行读取清单对每个 gem 执行git clone --depth1然后 checkout 到发布 tag优先v{version}否则{version}若指定了 revision 则直接 checkout 该 commit。这些克隆出来的源码用于在 Ruby 主仓库环境下测试捆绑 gem。在标准库仓库中构建拿到某个标准库独立仓库的代码后或为贡献准备的本地克隆第一步是安装其依赖bundle install这一步会读取仓库根目录的Gemfile与 gemspec把库自身运行与测试所需的 gem 依赖安装到本地。带 C 扩展的库需要编译如果该库带有/ext目录说明它包含需要编译的 C 文件例如性能关键路径的扩展必须先编译bundle exec rake compile为什么需要这一步以 ERB 的 C 扩展为例仓库中的 ext/erb/escape 目录包含 escape.c 与 extconf.rb。其extconf.rb会做一系列编译前探测检查rb_ext_ractor_safe函数与 Ruby Ractor 安全标记相关在非 JRuby/TruffleRuby 环境下探测当前 CPU 架构arm/aarch64 用 NEONx86_64 用 SSE2尝试编译一段 SIMD 小程序成功则定义ERB_ENABLE_SIMD宏以启用向量化转义路径可通过环境变量ERB_DISABLE_SIMD关闭该探测最终通过create_makefile erb/escape生成 Makefile。这段逻辑说明rake compile对这类库不是可选项而是让 Ruby 代码调用到本地优化实现如ERB::Escape的必要前提。同理ext/date、ext/stringio、ext/strscan 等目录都遵循“/ext目录 extconf.rb 编译”的模式。运行测试所有标准库统一使用 test-unit 作为测试框架本仓库 gems/bundled_gems 中即可找到test-unit 3.7.8的捆绑条目。测试目录约定为仓库内的test/测试文件命名如test/test_foo.rb。运行全部测试bundle exec rake test只跑单个测试文件bundle exec rake test TESTtest/test_foo.rb通过TEST变量指定目标文件适合在迭代某个模块时快速反馈。只跑单个测试用例bundle exec rake test TESTtest/test_foo.rb TESTOPTS--name/test_mytest/TESTOPTS透传给 test-unit 的命令行选项--name/正则/用正则匹配测试方法名test_mytest从而只执行指定的测试方法。深度印证Ruby 主仓库如何批量测试这些库如果你改动的库恰好也是捆绑 gem如 rexml、irb、csv 等Ruby 主仓库还提供了整体验证手段。脚本 tool/test-bundled-gems.rb 会遍历 gems/bundled_gems 中每个 gem其源码由tool/fetch-bundled_gems.rb克隆到gems/src/gem在各自目录下以本仓库构建出的ruby执行rake test并做并行调度、超时控制默认首轮 10 分钟与结果汇总。该脚本还体现了“允许失败”的边界处理通过DEFAULT_ALLOWED_FAILURES与TEST_BUNDLED_GEMS_ALLOW_FAILURES环境变量可以容忍特定平台下的已知失败如 Windows 下的 debug/irb/csv、缺少diff命令时的 minitest失败信息中会明确打印 “Ignoring test failures for ... due to ...”。常用调用方式# 测试全部捆绑 gem make test-bundled-gems # 只测试指定 gem make test-bundled-gems BUNDLED_GEMSgem1,gem2,gem3贡献流程总结综合本文向 Ruby 标准库提交贡献的完整路径是定位上游仓库通过 tool/sync_default_gems.rb 的 REPOSITORIES 表 或 gems/bundled_gems 清单确认目标库的独立仓库地址与版本在独立仓库开发clone 上游仓库先bundle install若库带/ext目录则再执行bundle exec rake compile本地验证bundle exec rake test跑全量或用TEST、TESTOPTS--name/.../精准回归提交 PR 到独立仓库改动会由 Ruby 团队的镜像流程tool/sync_default_gems.rb自动进入 Ruby 主仓库无需也不应直接在 lib 目录下手动改文件必要时刻参考维护者doc/maintainers.md 中的清单可帮你找到合适的 reviewer。牢记“镜像协作”这一核心前提你就能避免在错误的位置修改代码从而以正确的姿势参与 Ruby 标准库的建设。【免费下载链接】rubyThe Ruby Programming Language项目地址: https://gitcode.com/GitHub_Trending/ru/ruby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考