为 Ruby on Rails 做贡献

本指南涵盖了*你*如何成为 Ruby on Rails 持续开发的一部分。

阅读本指南后，您将了解

如何使用 GitHub 报告问题。
如何克隆 main 并运行测试套件。
如何帮助解决现有问题。
如何为 Ruby on Rails 文档做贡献。
如何为 Ruby on Rails 代码做贡献。

Ruby on Rails 并非“别人的框架”。多年来，成千上万的人为 Ruby on Rails 做出了贡献，从单个字符到大规模的架构更改或重要的文档——所有这些都是为了让 Ruby on Rails 对每个人都更好。即使你觉得自己还没有能力编写代码或文档，还有许多其他方式可以贡献，从报告问题到测试补丁。

如 Rails 的 README 中所述，所有在 Rails 及其子项目的代码库、问题跟踪器、聊天室、讨论板和邮件列表中进行交互的人都应遵守 Rails 的行为准则。

1. 报告问题

Ruby on Rails 使用 GitHub 问题跟踪来跟踪问题（主要是 bug 和新代码的贡献）。如果你在 Ruby on Rails 中发现了 bug，这里是开始的地方。你需要创建一个（免费的）GitHub 帐户才能提交问题、评论问题或创建 pull request。

最新发布的 Ruby on Rails 版本中的 bug 可能会得到最多的关注。此外，Rails 核心团队总是对那些花时间测试 *边缘 Rails*（目前正在开发的 Rails 版本的代码）的人的反馈感兴趣。在本指南的后面，你将了解如何获取边缘 Rails 进行测试。有关支持版本的信息，请参阅我们的维护策略。切勿在 GitHub 问题跟踪器上报告安全问题。

1.1. 创建错误报告

如果你在 Ruby on Rails 中发现了一个不是安全风险的问题，请在 GitHub 上搜索问题，以防它已被报告。如果你找不到任何解决你发现的问题的开放 GitHub 问题，你的下一步将是打开一个新问题。（有关报告安全问题，请参阅下一节。）

我们为你提供了一个问题模板，以便在创建问题时包含确定框架中是否存在错误所需的所有信息。每个问题都需要包含问题的标题和清晰描述。务必尽可能多地包含相关信息，包括演示预期行为的代码示例或失败测试，以及你的系统配置。你的目标应该是让你自己和其他人轻松重现 bug 并找出解决方案。

一旦你打开一个问题，它可能不会立即得到活动，除非它是“红色代码、任务关键、世界末日”之类的 bug。这并不意味着我们不关心你的 bug，只是有许多问题和 pull request 需要处理。遇到相同问题的其他人可能会找到你的问题，并确认 bug，并可能与你协作修复它。如果你知道如何修复 bug，请继续并打开一个 pull request。

1.2. 创建可执行测试用例

有一种方法可以重现你的问题，这将有助于人们确认、调查并最终解决你的问题。你可以通过提供可执行测试用例来做到这一点。为了使此过程更容易，我们准备了几个 bug 报告模板供你作为起点使用

这些模板包含设置测试用例的样板代码。将适当模板的内容复制到 .rb 文件中，并进行必要的更改以演示问题。你可以在终端中运行 ruby the_file.rb 来执行它。如果一切顺利，你应该会看到你的测试用例失败。

然后你可以将你的可执行测试用例作为 gist 分享，或者将内容粘贴到问题描述中。

1.3. 安全问题的特殊处理

请不要使用公共 GitHub 问题报告来报告安全漏洞。Rails 安全策略页面详细说明了处理安全问题的程序。

1.4. 功能请求怎么办？

请不要将“功能请求”项目放入 GitHub Issues 中。如果你想在 Ruby on Rails 中添加新功能，你需要自己编写代码——或者说服其他人与你合作编写代码。在本指南的后面，你将找到关于向 Ruby on Rails 提议补丁的详细说明。如果你在 GitHub Issues 中输入了一个没有代码的愿望清单项，你可以预期它在审查后会立即被标记为“无效”。

有时，“bug”和“功能”之间的界限很难划分。通常，功能是任何增加新行为的东西，而 bug 是任何导致不正确行为的东西。有时，核心团队将不得不做出判断。话虽如此，这种区别通常决定了你的更改将随哪个补丁发布；我们喜欢功能提交！它们只是不会被反向移植到维护分支。

如果你想在制作补丁之前就某个功能的想法获得反馈，请在 rails-core 讨论板上开始讨论。你可能得不到任何回复，这意味着每个人都无动于衷。你可能会找到一个也对构建该功能感兴趣的人。你可能会得到一个“这不会被接受”的回复。但这是讨论新想法的合适场所。GitHub Issues 对于有时漫长而复杂的新功能所需的讨论来说并不是一个特别好的场所。

2. 帮助解决现有问题

除了报告问题之外，你还可以通过提供反馈来帮助核心团队解决现有问题。如果你是 Rails 核心开发的新手，提供反馈将帮助你熟悉代码库和流程。

如果你查看 GitHub Issues 中的问题列表，你会发现许多问题已经需要关注。你能做些什么呢？实际上很多

2.1. 验证错误报告

首先，验证错误报告本身就很有帮助。你能在自己的电脑上重现报告的问题吗？如果能，你可以在问题中添加评论，说明你也看到了同样的问题。

如果一个问题非常模糊，你能否帮助将其范围缩小到更具体的内容？也许你可以提供更多信息来重现 bug，或者你可以消除演示问题不需要的步骤。

如果你发现一个没有测试的错误报告，贡献一个失败的测试会非常有用。这也是探索源代码的好方法：查看现有测试文件将教会你如何编写更多测试。新测试最好以补丁的形式贡献，正如贡献 Rails 代码部分后面解释的那样。

你所能做的任何事情，只要能使错误报告更简洁或更容易重现，都会帮助那些试图编写代码来修复这些错误的人——无论你最终是否自己编写代码。

2.2. 测试补丁

你还可以通过检查通过 GitHub 提交到 Ruby on Rails 的 pull request 来提供帮助。要应用某人的更改，首先创建一个专门的分支

$ git checkout -b testing_branch

然后，你可以使用他们的远程分支来更新你的代码库。例如，假设 GitHub 用户 JohnSmith 已经 fork 并推送到位于 https://github.com/JohnSmith/rails 的主题分支“orange”。

$ git remote add JohnSmith https://github.com/JohnSmith/rails.git
$ git pull JohnSmith orange

除了将他们的远程添加到你的 checkout 之外，另一种选择是使用 GitHub CLI 工具来 checkout 他们的 pull request。

应用分支后，进行测试！以下是一些需要考虑的事情

更改是否真的有效？
你对测试满意吗？你能理解它们在测试什么吗？是否有任何测试缺失？
它是否有适当的文档覆盖？其他地方的文档是否需要更新？
你喜欢这个实现吗？你能想出一种更好或更快的方式来实现在他们更改中的一部分吗？

一旦你确定 pull request 包含了一个好的更改，请在 GitHub issue 上评论，说明你的发现。你的评论应该表明你喜欢这个更改以及你喜欢它的哪些方面。例如

我喜欢你在 generate_finder_sql 中重构代码的方式——好多了。测试看起来也不错。

如果你的评论只是“+1”，那么其他审阅者很可能不会太认真对待。请表明你花时间审阅了 pull request。

3. 贡献 Rails 文档

Ruby on Rails 有两套主要的文档：指南，帮助你学习 Ruby on Rails；以及 API，作为参考。

你可以通过使 Rails 指南或 API 参考更连贯、一致或可读，添加缺失信息，纠正事实错误，修正拼写错误，或使其与最新的边缘 Rails 保持同步来帮助改进它们。

为此，请修改 Rails 指南源文件（在 GitHub 上位于此处）或源代码中的 RDoc 注释。然后打开一个 pull request 以将你的更改应用到 main 分支。

在你的 pull request 标题中使用 [ci skip] 以避免为文档更改运行 CI 构建。

一旦你打开 PR，文档的预览将被部署，以便于审阅和协作。在 Pull Request 页面的底部，你应该会看到一个状态检查列表，查找 buildkite/docs-preview 并点击“详细信息”。

GitHub rails/rails Pull Request status checks

这将把你带到 Buildkite 构建页面。如果作业成功，任务列表上方将有一个带有指向生成的 API 和指南链接的注释。

Buildkite rails/docs-preview annotation API & Guides links

在处理文档时，请考虑 API 文档指南和 Ruby on Rails 指南准则。

4. 翻译 Rails 指南

我们很高兴有志愿者翻译 Rails 指南。只需按照以下步骤操作

Fork https://github.com/rails/rails。
为你的语言添加一个源文件夹，例如：意大利语的 guides/source/it-IT。
将 guides/source 的内容复制到你的语言目录并进行翻译。
请勿翻译 HTML 文件，因为它们是自动生成的。

请注意，翻译不会提交到 Rails 仓库；你的工作存在于你的 fork 中，如上所述。这是因为，在实践中，通过补丁维护文档只在英语中是可持续的。

要以 HTML 格式生成指南，你需要安装指南依赖项，cd 到 guides 目录，然后运行（例如，对于 it-IT）

$ BUNDLE_ONLY=default:doc bundle install
$ cd guides/
$ BUNDLE_ONLY=default:doc bundle exec rake guides:generate:html GUIDES_LANGUAGE=it-IT

这将在 output 目录中生成指南。

Redcarpet Gem 不适用于 JRuby。

5. 贡献 Rails 代码

5.1. 设置开发环境

要从提交 bug 转向帮助解决现有问题或向 Ruby on Rails 贡献你自己的代码，你*必须*能够运行其测试套件。在本指南的这一部分中，你将学习如何在你的计算机上设置测试。

5.1.1. 使用 GitHub Codespaces

如果你是启用 Codespaces 的组织成员，你可以将 Rails fork 到该组织并在 GitHub 上使用 Codespaces。Codespace 将使用所有必需的依赖项进行初始化，并允许你运行所有测试。

5.1.2. 使用 VS Code 远程容器

如果你安装了 Visual Studio Code 和 Docker，你可以使用 VS Code 远程容器插件。该插件将读取仓库中的 .devcontainer 配置并在本地构建 Docker 容器。

5.1.3. 使用 Dev Container CLI

安装 npm 和 Docker 后，你可以运行 Dev Container CLI 从命令行使用 .devcontainer 配置。

$ npm install -g @devcontainers/cli
$ cd rails
$ devcontainer up --workspace-folder .
$ devcontainer exec --workspace-folder . bash

5.1.4. 将 Dev Container 与 Podman 结合使用

你可以将 .devcontainer 配置与 Podman 结合使用。此方法除了 Podman 之外不需要任何其他工具。

$ podman machine init
$ podman machine start
$ tools/devcontainer up

然后在另一个终端中

$ tools/devcontainer run-user-commands
$ tools/devcontainer sh

5.1.5. 使用 rails-dev-box

也可以使用 rails-dev-box 来准备开发环境。但是，rails-dev-box 使用 Vagrant 和 Virtual Box，这在配备 Apple 芯片的 Mac 上无法工作。

5.1.6. 本地开发

当你无法使用 GitHub Codespaces 时，请参阅本指南了解如何设置本地开发。这被认为是一种困难的方式，因为安装依赖项可能因操作系统而异。

5.2. 克隆 Rails 仓库

为了能够贡献代码，你需要克隆 Rails 仓库

$ git clone https://github.com/rails/rails.git

并创建一个专门的分支

$ cd rails
$ git checkout -b my_new_branch

你使用什么名称并不重要，因为此分支只存在于你的本地计算机和你在 GitHub 上的个人仓库中。它不会成为 Rails Git 仓库的一部分。

5.3. Bundle 安装

安装所需的 Gem。

$ bundle install

5.4. 针对本地分支运行应用程序

如果你需要一个虚拟 Rails 应用来测试更改，rails new 的 --dev 标志会生成一个使用你的本地分支的应用

$ cd rails
$ bundle exec rails new ~/my-test-app --dev

在 ~/my-test-app 中生成的应用程序将针对你的本地分支运行，特别是在服务器重启后会看到任何修改。

对于 JavaScript 包，你可以使用 yarn link 在生成的应用程序中引用你的本地分支

$ cd rails/activestorage
$ yarn link
$ cd ~/my-test-app
$ yarn link "@rails/activestorage"

5.5. 编写代码

现在是时候编写一些代码了！在为 Rails 做更改时，请记住以下几点

遵循 Rails 的风格和约定。
使用 Rails 的惯用语和辅助方法。
包含在没有你的代码时失败，在有你的代码时通过的测试。
更新（周围的）文档、其他地方的示例和指南：任何受你的贡献影响的内容。
如果更改添加、删除或修改了功能，请务必包含 CHANGELOG 条目。如果你的更改是错误修复，则不需要 CHANGELOG 条目。

仅具有美观性但未实质性增加 Rails 稳定性、功能或可测试性的更改通常不会被接受（阅读更多关于我们做出此决定的理由）。

5.5.1. 遵循编码约定

Rails 遵循一套简单的编码风格约定

两个空格，无制表符（用于缩进）。
无尾随空格。空行不应包含任何空格。
在 private/protected 后缩进且无空行。
哈希使用 Ruby >= 1.9 语法。优先使用 { a: :b } 而不是 { :a => :b }。
优先使用 &&/|| 而不是 and/or。
类方法优先使用 class << self 而不是 self.method。
使用 my_method(my_arg) 而不是 my_method( my_arg ) 或 my_method my_arg。
使用 a = b 而不是 a=b。
使用 assert_not 方法而不是 refute。
单行块优先使用 method { do_stuff } 而不是 method{do_stuff}。
遵循你已经使用的源代码中的约定。

以上是指导方针——请你酌情使用。

此外，我们还定义了 RuboCop 规则来规范我们的一些编码约定。你可以在提交 pull request 之前在本地针对你修改的文件运行 RuboCop

$ bundle exec rubocop actionpack/lib/action_controller/metal/strong_parameters.rb
Inspecting 1 file
.

1 file inspected, no offenses detected

5.6. 对代码进行基准测试

对于可能对性能产生影响的更改，请对你的代码进行基准测试并测量影响。请分享你使用的基准测试脚本以及结果。你应该考虑将此信息包含在你的提交消息中，以便未来的贡献者可以轻松验证你的发现并确定它们是否仍然相关。（例如，Ruby VM 中未来的优化可能会使某些优化变得不必要。）

当你针对你关心的特定场景进行优化时，很容易导致其他常见情况的性能下降。因此，你应该针对一系列代表性场景测试你的更改，最好是从实际生产应用程序中提取的。

你可以使用基准测试模板作为起点。它包含使用 benchmark-ips gem 设置基准测试的样板代码。该模板旨在测试可以内联到脚本中的相对独立的更改。

5.7. 运行测试

在 Rails 中，在推送更改之前运行完整的测试套件并不常见。railties 测试套件尤其需要很长时间，如果源代码安装在 /vagrant 中（如推荐的 rails-dev-box 工作流程中那样），则需要特别长的时间。

作为折衷，请测试你的代码明显影响的内容，如果更改不在 railties 中，则运行受影响组件的整个测试套件。如果所有测试都通过，则足以提交你的贡献。我们有 Buildkite 作为安全网，以捕获其他地方意外的故障。

5.7.1. 整个 Rails

要运行所有测试，请执行

$ cd rails
$ bundle exec rake test

5.7.2. 对于特定组件

你只能运行特定组件（例如 Action Pack）的测试。例如，要运行 Action Mailer 测试

$ cd actionmailer
$ bin/test

5.7.3. 从仓库根目录运行组件测试

你还可以使用 rake 任务从仓库根目录运行组件测试套件

$ bundle exec rake actionpack:test
$ bundle exec rake actionpack:isolated

# Active Record adapters (from the repo root)
$ bundle exec rake activerecord:sqlite3:test
$ bundle exec rake activerecord:sqlite3:isolated
$ bundle exec rake activerecord:mysql2:test
$ bundle exec rake activerecord:trilogy:test
$ bundle exec rake activerecord:postgresql:test

# Active Record integration tests (Active Job integration across adapters)
$ bundle exec rake activerecord:integration

# Active Job adapters
$ bundle exec rake activejob:sidekiq:test
$ bundle exec rake activejob:sidekiq:isolated
$ bundle exec rake activejob:sidekiq:integration

# All Active Job integration tests
$ bundle exec rake activejob:integration

注意

并非所有框架都定义了独立的测试任务。例如，不支持 activestorage:isolated 并将以错误退出。

5.7.4. 对于特定目录

你只能运行特定组件（例如 Active Storage 中的模型）的特定目录的测试。例如，要在 /activestorage/test/models 中运行测试

$ cd activestorage
$ bin/test models

5.7.5. 对于特定文件

你可以运行特定文件的测试

$ cd actionview
$ bin/test test/template/form_helper_test.rb

5.7.6. 运行单个测试

你可以使用 -n 选项按名称运行单个测试

$ cd actionmailer
$ bin/test test/mail_layout_test.rb -n test_explicit_class_layout

5.7.7. 对于特定行

找出名称并不总是容易，但如果你知道测试开始的行号，此选项适合你

$ cd railties
$ bin/test test/application/asset_debugging_test.rb:69

5.7.8. 对于特定行范围

相似的测试通常定义在附近的同一位置。你可以在特定行范围运行测试。

$ cd railties
$ bin/test test/application/asset_debugging_test.rb:69-100

5.7.9. 使用特定种子运行测试

测试执行使用随机化种子进行随机化。如果你遇到随机测试失败，可以通过专门设置随机化种子来更准确地重现失败的测试场景。

运行组件的所有测试

$ cd actionmailer
$ SEED=15002 bin/test

运行单个测试文件

$ cd actionmailer
$ SEED=15002 bin/test test/mail_layout_test.rb

5.7.10. 串行运行测试

Action Pack 和 Action View 单元测试默认并行运行。如果你遇到随机测试失败，可以通过设置 PARALLEL_WORKERS=1 来设置随机化种子并让这些单元测试串行运行

$ cd actionview
$ PARALLEL_WORKERS=1 SEED=53708 bin/test test/template/test_case_test.rb

5.7.11. 测试 Active Record

首先，创建你需要的数据库。你可以在 activerecord/test/config.example.yml 中找到所需表名、用户名和密码的列表。

对于 MySQL 和 PostgreSQL，只需运行

$ cd activerecord
$ bundle exec rake db:mysql:build

或者

$ cd activerecord
$ bundle exec rake db:postgresql:build

SQLite3 不需要这样做。

从仓库根目录，等效的数据库管理任务在 activerecord:db 命名空间下可用

# Create both MySQL and PostgreSQL test databases
$ bundle exec rake activerecord:db:create

# Drop both MySQL and PostgreSQL test databases
$ bundle exec rake activerecord:db:drop

# Rebuild both MySQL and PostgreSQL test databases
$ bundle exec rake activerecord:db:rebuild

# Manage MySQL databases only
$ bundle exec rake activerecord:db:mysql:build
$ bundle exec rake activerecord:db:mysql:drop
$ bundle exec rake activerecord:db:mysql:rebuild

# Manage PostgreSQL databases only
$ bundle exec rake activerecord:db:postgresql:build
$ bundle exec rake activerecord:db:postgresql:drop
$ bundle exec rake activerecord:db:postgresql:rebuild

以下是如何仅为 SQLite3 运行 Active Record 测试套件的方法

$ cd activerecord
$ bundle exec rake test:sqlite3

从仓库根目录，可以使用等效命令

$ bundle exec rake activerecord:sqlite3:test

你现在可以像对 sqlite3 一样运行测试了。任务分别是

$ bundle exec rake test:mysql2
$ bundle exec rake test:trilogy
$ bundle exec rake test:postgresql

或者

$ bundle exec rake activerecord:mysql2:test
$ bundle exec rake activerecord:trilogy:test
$ bundle exec rake activerecord:postgresql:test

最后，

$ bundle exec rake test

现在将依次运行这三个。

你可以运行适配器特定的独立测试，或所有 Active Record 的 Active Job 集成测试，使用

# From inside activerecord
$ bundle exec rake test:isolated:sqlite3
$ bundle exec rake test:integration:active_job

# Or repository root
$ bundle exec rake activerecord:sqlite3:isolated
$ bundle exec rake activerecord:integration   # runs Active Job integration across all adapters

你也可以单独运行任何单个测试

$ ARCONN=mysql2 bundle exec ruby -Itest test/cases/associations/has_many_associations_test.rb

要针对所有适配器运行单个测试，请使用

$ bundle exec rake TEST=test/cases/associations/has_many_associations_test.rb

你也可以调用 test_jdbcmysql、test_jdbcsqlite3 或 test_jdbcpostgresql。有关运行更具针对性的数据库测试的信息，请参阅文件 activerecord/RUNNING_UNIT_TESTS.rdoc。

5.7.12. 使用调试器进行测试

要使用外部调试器（pry、byebug 等），请安装调试器并正常使用。如果出现调试器问题，请通过设置 PARALLEL_WORKERS=1 串行运行测试，或通过 -n test_long_test_name 运行单个测试。

如果对生成器运行测试，你需要设置 RAILS_LOG_TO_STDOUT=true，以便调试工具能够工作。

RAILS_LOG_TO_STDOUT=true ./bin/test test/generators/actions_test.rb

5.8. 警告

测试套件在启用警告的情况下运行。理想情况下，Ruby on Rails 不应发出任何警告，但可能有一些，以及一些来自第三方库的警告。请忽略（或修复！）它们，如果有的话，并提交不会发出新警告的补丁。

如果引入了警告，Rails CI 将会报错。要在本地实现相同的行为，请在运行测试套件时设置 RAILS_STRICT_WARNINGS=1。

5.9. 更新文档

Ruby on Rails 指南提供了 Rails 功能的高级概述，而 API 文档则深入探讨细节。

如果你的 PR 添加了新功能或更改了现有功能的行为，请检查相关文档并根据需要进行更新或添加。

例如，如果你修改 Active Storage 的图像分析器以添加新的元数据字段，你应该更新 Active Storage 指南的分析文件部分以反映这一点。

5.10. 更新 CHANGELOG

CHANGELOG 是每个发布的重要组成部分。它记录了每个 Rails 版本的更改列表。

如果你正在添加或删除功能，或添加弃用通知，你应该在修改的框架的 CHANGELOG *顶部*添加一个条目。重构、次要错误修复和文档更改通常不应写入 CHANGELOG。

CHANGELOG 条目应总结更改内容，并以作者姓名结尾。如果需要更多空间，可以使用多行，并且可以附加缩进 4 个空格的代码示例。如果更改与特定问题相关，则应附加问题的编号。这是一个 CHANGELOG 条目示例

*   Summary of a change that briefly describes what was changed. You can use multiple
    lines and wrap them at around 80 characters. Code examples are ok, too, if needed:

        class Foo
          def bar
            puts 'baz'
          end
        end

    You can continue after the code example, and you can attach the issue number.

    Fixes #1234.

    *Your Name*

5.11. 破坏性更改

任何可能破坏现有应用程序的更改都被认为是破坏性更改。为了方便升级 Rails 应用程序，破坏性更改需要一个弃用周期。

5.11.1. 移除行为

如果你的破坏性更改移除了现有行为，你首先需要添加弃用警告，同时保留现有行为。

例如，假设你想删除 ActiveRecord::Base 上的一个公共方法。如果 main 分支指向未发布的 7.0 版本，Rails 7.0 将需要显示弃用警告。这确保任何升级到任何 Rails 7.0 版本的人都会看到弃用警告。在 Rails 7.1 中，该方法可以被删除。

你可以添加以下弃用警告

def deprecated_method
  ActiveRecord.deprecator.warn(<<-MSG.squish)
    `ActiveRecord::Base.deprecated_method` is deprecated and will be removed in Rails 7.1.
  MSG
  # Existing behavior
end

5.11.2. 更改行为

如果你的破坏性更改改变了现有行为，你需要添加一个框架默认值。框架默认值通过允许应用程序逐个切换到新默认值来简化 Rails 升级。

要实现新的框架默认值，首先通过在目标框架上添加访问器来创建配置。将默认值设置为现有行为，以确保在升级过程中不会出现任何问题。

module ActiveJob
  mattr_accessor :existing_behavior, default: true
end

新配置允许你条件性地实现新行为

def changed_method
  if ActiveJob.existing_behavior
    # Existing behavior
  else
    # New behavior
  end
end

要设置新的框架默认值，请在 Rails::Application::Configuration#load_defaults 中设置新值

def load_defaults(target_version)
  case target_version.to_s
  when "7.1"
    # ...
    if respond_to?(:active_job)
      active_job.existing_behavior = false
    end
    # ...
  end
end

为了简化升级，需要将新默认值添加到 new_framework_defaults 模板中。添加一个注释掉的部分，设置新值

# new_framework_defaults_8_1.rb.tt

# Rails.application.config.active_job.existing_behavior = false

最后一步，将新的配置添加到 configuration.md 中的配置指南中

#### `config.active_job.existing_behavior

| Starting with version | The default value is |
| --------------------- | -------------------- |
| (original)            | `true`               |
| 7.1                   | `false`              |

5.12. 忽略编辑器/IDE 创建的文件

一些编辑器和 IDE 会在 rails 文件夹中创建隐藏文件或文件夹。与其手动将这些文件从每个提交中排除或将其添加到 Rails 的 .gitignore 中，你不如将它们添加到你自己的全局 gitignore 文件中。

5.13. 更新 Gemfile.lock

某些更改需要依赖项升级。在这种情况下，请确保运行 bundle update 以获取正确的依赖项版本，并在你的更改中提交 Gemfile.lock 文件。

5.14. 提交更改

当你对计算机上的代码满意时，你需要将更改提交到 Git

$ git commit -a

这应该会启动你的编辑器来编写提交消息。完成后，保存并关闭以继续。

一个格式良好且描述性强的提交消息对于其他人理解更改的原因非常有帮助，所以请花时间编写它。

一个好的提交消息看起来像这样

Short summary (ideally 50 characters or less)

More detailed description, if necessary. Each line should wrap at
72 characters. Try to be as descriptive as you can. Even if you
think that the commit content is obvious, it may not be obvious
to others. Add any description that is already present in the
relevant issues; it should not be necessary to visit a webpage
to check the history.

The description section can have multiple paragraphs.

Code examples can be embedded by indenting them with 4 spaces:

    class ArticlesController
      def index
        render json: Article.limit(10)
      end
    end

You can also add bullet points:

- make a bullet point by starting a line with either a dash (-)
  or an asterisk (*)

- wrap lines at 72 characters, and indent any additional lines
  with 2 spaces for readability

请酌情将你的提交压缩成一个单独的提交。这简化了未来的 cherry pick 并保持了 git 日志的整洁。

5.15. 更新分支

在你工作期间，主分支很可能发生了其他更改。要获取主分支中的新更改

$ git checkout main
$ git pull --rebase

现在将你的补丁重新应用到最新更改之上

$ git checkout my_new_branch
$ git rebase main

没有冲突？测试仍然通过？更改对你来说仍然合理吗？然后将 rebase 后的更改推送到 GitHub

$ git push --force-with-lease

我们禁止在 rails/rails 仓库基础分支上强制推送，但你可以在你的 fork 上强制推送。当进行 rebase 时，这是一个要求，因为历史已经改变。

5.16. Fork

导航到 Rails GitHub 仓库，然后点击右上角的“Fork”。

将新的远程添加到你的本地机器上的本地仓库中

$ git remote add fork https://github.com/<your username>/rails.git

你可能已经从 rails/rails 克隆了你的本地仓库，或者你可能已经从你的 fork 仓库克隆了。以下 git 命令假定你已经创建了一个指向 rails/rails 的“rails”远程。

$ git remote add rails https://github.com/rails/rails.git

从官方仓库下载新的提交和分支

$ git fetch rails

合并新内容

$ git checkout main
$ git rebase rails/main
$ git checkout my_new_branch
$ git rebase rails/main

更新你的 fork

$ git push fork main
$ git push fork my_new_branch

5.17. 打开 Pull Request

导航到你刚刚推送到的 Rails 仓库（例如，https://github.com/your-user-name/rails），然后点击顶部栏中的“Pull Requests”（代码上方）。在下一页，点击右上角的“New pull request”。

Pull Request 应该以 rails/rails 基础仓库和 main 分支为目标。头部仓库将是你的工作（your-user-name/rails），分支将是你给你的分支起的任何名称。准备好后点击“create pull request”。

确保你引入的更改集已包含在内。使用提供的 pull request 模板填写有关你的潜在补丁的一些详细信息。完成后，点击“Create pull request”。

5.18. 获取一些反馈

大多数 pull request 在合并之前都会经历几次迭代。不同的贡献者有时会有不同的意见，并且通常补丁需要修改才能合并。

一些 Rails 贡献者打开了 GitHub 的电子邮件通知，但其他人没有。此外，几乎所有 Rails 工作人员都是志愿者，因此你可能需要几天才能在 pull request 上获得第一次反馈。不要灰心！有时很快，有时很慢。这就是开源生活。

如果已经超过一周，并且你还没有收到任何消息，你可能需要尝试推动一下。你可以使用 Ruby on Rails Discord 服务器中的 *contributions* 频道，或者 rubyonrails-core 讨论板。你也可以在 pull request 上留下另一条评论。最好避免直接 ping 个人维护者，因为我们的带宽有限，可能无法查看你的 PR。

在你等待 pull request 的反馈时，打开其他几个 pull request 并给别人一些！他们会像你感谢你的补丁反馈一样感谢你。

请注意，只有核心团队和提交者团队被允许合并代码更改。如果有人提供反馈并“批准”你的更改，他们可能没有能力或最终决定权来合并你的更改。

5.19. 根据需要进行迭代

你收到的反馈完全有可能建议更改。不要气馁：为活跃的开源项目做贡献的全部意义在于利用社区的知识。如果人们鼓励你调整代码，那么值得进行调整并重新提交。如果反馈是你的代码不会被合并，你仍然可以考虑将其作为 gem 发布。

5.19.1. 压缩提交

我们可能会要求你做的事情之一是“压缩你的提交”，这会将你的所有提交合并成一个单独的提交。我们更喜欢单个提交的 pull request。这使得将更改向后移植到稳定分支更容易，压缩使得回滚错误的提交更容易，并且 git 历史记录也更容易跟踪。Rails 是一个大型项目，一堆多余的提交会增加很多噪音。

$ git fetch rails
$ git checkout my_new_branch
$ git rebase -i rails/main

< Choose 'squash' for all of your commits except the first one. >
< Edit the commit message to make sense, and describe all your changes. >

$ git push fork my_new_branch --force-with-lease

你应该能够刷新 GitHub 上的 pull request 并看到它已经更新。

5.19.2. 更新 Pull Request

有时你会需要对已经提交的代码进行一些更改。这可能包括修改现有提交。在这种情况下，Git 不允许你推送更改，因为已推送的分支和本地分支不匹配。你可以强制推送到你在 GitHub 上的分支，如前面压缩提交部分所述，而不是打开一个新的 pull request

$ git commit --amend
$ git push fork my_new_branch --force-with-lease

这将使用你的新代码更新 GitHub 上的分支和 pull request。通过使用 --force-with-lease 强制推送，git 将比使用典型的 -f 更安全地更新远程，后者可能会删除远程中你没有的工作。

5.20. 旧版本的 Ruby on Rails

如果你想为早于下一个发布版本的 Ruby on Rails 版本添加修复，你需要设置并切换到你自己的本地跟踪分支。以下是切换到 7-0-stable 分支的示例

$ git branch --track 7-0-stable rails/7-0-stable
$ git checkout 7-0-stable

在处理旧版本之前，请查阅维护策略。对于已达到生命周期结束的版本，更改将不被接受。

5.20.1. 反向移植

合并到 main 的更改旨在用于 Rails 的下一个主要版本。有时，将你的更改传播回稳定分支以包含在维护版本中可能会有益。通常，安全修复和错误修复是反向移植的好选择，而新功能和更改预期行为的补丁将不被接受。如有疑问，最好在反向移植更改之前咨询 Rails 团队成员，以避免徒劳无功。

首先，确保你的 main 分支是最新的。

$ git checkout main
$ git pull --rebase

检查你要反向移植到的分支，例如 7-0-stable，并确保它是最新的

$ git checkout 7-0-stable
$ git reset --hard origin/7-0-stable
$ git checkout -b my-backport-branch

如果你正在反向移植一个已合并的 pull request，请找到合并的提交并 cherry-pick 它

$ git cherry-pick -m1 MERGE_SHA

解决 cherry-pick 中发生的任何冲突，推送你的更改，然后打开一个指向你要反向移植到的稳定分支的 PR。如果你有一组更复杂的更改，cherry-pick 文档可以提供帮助。

6. Rails 贡献者

所有贡献者都会在 Rails 贡献者中获得荣誉。