How to contribute

This section covers the contributor workflow for the Rails codebase: how to pick up work, run tests, follow code style, and ship a pull request.

The canonical, user-facing version of this guide lives at https://edgeguides.rubyonrails.org/contributing_to_ruby_on_rails.html. The pages here are a developer-oriented summary keyed to specific files in the repo.

Sub-pages

• Development workflow — branch, code, test, PR, merge.
• Testing — Minitest, parallel runs, the Active Record adapter matrix, fixtures, and helpers.
• Debugging — common pitfalls, where logs go, how to bisect.
• Patterns and conventions — the code style that spans every component.
• Tooling — RuboCop, mdl, the bin/test wrapper, CI, devcontainers.

Where to start

If you've never contributed before:

1. Read CONTRIBUTING.md at the repo root.
2. Read AGENTS.md — it documents the conventions explicitly for AI/automated contributors but is just as useful for humans.
3. Read the per-component README.{md,rdoc} for whatever component you're touching.
4. Check the *-stable branches for backporting policy if your fix needs to ship on a maintenance release.
5. Look at the bug-report templates in guides/bug_report_templates/ if you need to reproduce something for an issue.

Pull request expectations

• One coherent change per PR. Refactors and behavior changes should be separate.
• Add an entry to the relevant <component>/CHANGELOG.md for behavior changes.
• Include tests. The repo treats untested behavior as not promised.
• Reference the issue number in the commit body (Fix #12345: Description).
• Run bundle exec rubocop and the affected component's bin/test before pushing.

The maintainers' review priorities, in rough order, are: correctness, performance regressions, test coverage, code style, documentation, and changelog. Rails has a very high bar for adding new public API; bug fixes and removing dead code tend to merge much faster than additions.

Definition of done

A change is considered done when:

• The component's tests pass locally on the relevant adapter(s).
• RuboCop is clean.
• A CHANGELOG.md entry exists for any behavior change.
• The PR has been reviewed and approved by a committer.
• For Active Record changes, all four adapter test suites pass on CI.

For deep technical conventions (configuration flags, helper layout, naming), see patterns and conventions. For test specifics, see testing.