Development workflow

The branch-code-test-PR cycle for the Rails codebase.

Branch model

• main — the next major/minor release. Currently 8.2.0.alpha.
• X.Y-stable — maintenance branch for the released X.Y line. At time of writing, the active stable branches are 8.1-stable, 8.0-stable, 7.2-stable, and 7.1-stable.
• Bug fixes that need to ship on a stable release land on main first and are then backported by a maintainer.

For most contributions you only need to push to a feature branch off main.

Standard cycle

# Fork on GitHub, then:
git clone git@github.com:<you>/rails.git
cd rails
git remote add upstream git@github.com:rails/rails.git

# Start a topic branch
git checkout -b fix-some-bug

# Make changes, run the relevant component's tests
cd activerecord && bin/test

# Commit, push, open a PR against rails/rails main
git commit -m "Fix #12345: ActiveRecord no longer mutates frozen X"
git push origin fix-some-bug

Cross-component changes

A typical cross-component fix (per AGENTS.md) touches several files:

1. The implementation in <component>/lib/....

2. The tests in <component>/test/....

3. The <component>/CHANGELOG.md.

4. (Sometimes) related helpers in sibling files — when you add a configuration flag, grep for similar patterns:

   rg "unless ActionView::Base.remove_hidden_field_autocomplete" actionview/lib

Configuration flags introduced in a new Rails version are also wired into railties/lib/rails/application/configuration.rb under load_defaults.

Commit message style

Fix #12345: Short imperative summary

Longer explanation if needed. Explain why, not what — the diff
shows what.

Patterns to match:

• Reference issues with Fix #N or Closes #N so GitHub auto-closes them.
• Squash work-in-progress commits before opening the PR.
• Keep refactors and behavior changes in separate commits when possible.

Changelog format

Each component owns a CHANGELOG.md. New entries go at the top of the file. The shape is:

- Brief description of the change. Mention any user-facing API change
  or migration step. Wrap at ~80 columns.

  _Your Name_

The change is in italics by virtue of *…*, and the author signature line is also wrapped in *. See existing entries in activerecord/CHANGELOG.md and railties/CHANGELOG.md for the pattern.

Backports

If your fix is a regression on a stable branch, a maintainer will cherry-pick it to the relevant *-stable branch after it merges to main. Don't open the backport PR yourself unless asked — the policy varies per release.

Working on the guides

guides/source/*.md contains the source for https://guides.rubyonrails.org. To preview locally:

cd guides
bundle exec rake guides:generate
open output/index.html

Style is enforced by mdl via .mdlrc.rb.

Testing your change inside a real Rails app

cd /tmp
ruby /path/to/rails/railties/exe/rails new myapp --dev
cd myapp
bin/rails server

--dev rewrites the new app's Gemfile to use path: references back to your checkout, so iterations are immediate.

For more involved scenarios, the guides/bug_report_templates/ directory contains self-contained executable_template.rb scripts that build a tiny Rails app and reproduce a specific bug. They're a great way to share a minimal repro on an issue.

Submitting

1. Push to your fork.
2. Open a PR against rails/rails:main.
3. CI runs the matrix (multiple Ruby versions, all four AR adapters, RuboCop, JS lint, devcontainer build). See tooling for details.
4. Address review feedback in additional commits — squash before merge if asked.

See testing for everything about running suites locally, and patterns and conventions for the rules CI enforces.