Getting started

This page covers what you need to start hacking on the Rails framework itself. If you want to use Rails to build an application, follow the Getting Started Rails Guide instead.

Prerequisites

• Ruby 3.3.1+ — declared in rails.gemspec (required_ruby_version).
• Bundler — comes with modern Ruby; required to install dev dependencies.
• Git — the only way to clone the repo.
• A C toolchain — needed for native gem extensions (sqlite3, mysql2, ffi).
• Database servers (optional) — only required if you want to run Active Record's full adapter matrix:
  • SQLite (built-in on macOS/Linux)
  • PostgreSQL
  • MySQL or MariaDB
  • Trilogy uses MySQL's wire protocol
• Node + Yarn (optional) — only required if you're touching JavaScript packages (actioncable, activestorage, actiontext).

A Brewfile at the repo root captures the macOS Homebrew packages needed for full local development.

A .devcontainer/ directory provides a Docker-based development setup if you'd rather not install dependencies locally.

Clone and bootstrap

git clone https://github.com/rails/rails.git
cd rails
bundle install

bundle install reads the top-level Gemfile, which uses gemspec to pull in dependencies for every component plus the dev/test extras (Minitest, Capybara, Selenium, RuboCop, etc.).

Repository layout at a glance

rails/
├── activesupport/  activemodel/  activerecord/
├── actionpack/     actionview/   actionmailer/
├── actionmailbox/  activejob/    actioncable/
├── activestorage/  actiontext/   railties/
├── guides/         # Source for guides.rubyonrails.org
├── tools/          # Shared test runner + releaser
├── tasks/          # Cross-component rake tasks
├── Gemfile         # One Gemfile for the whole monorepo
└── rails.gemspec   # The top-level meta-gem

Each component has the same shape: lib/, test/, bin/test, Rakefile, CHANGELOG.md, and a gemspec.

Running tests

There are two layers: per-component runners (preferred for fast feedback) and rake tasks at the repo root.

Run a single component's suite

cd actionview
bin/test

bin/test is a tiny wrapper that loads tools/test.rb and shells out to Rails::TestUnit::Runner (the same code that powers bin/rails test in apps).

You can target a specific file or test name:

bin/test test/template/form_helper_test.rb
bin/test test/template/form_helper_test.rb -n "/hidden_field/"
bin/test test/template/form_helper_test.rb::FormHelperTest#test_hidden_field

Active Record adapter matrix

Active Record runs against multiple database adapters. The default is SQLite:

cd activerecord
bundle exec rake test:sqlite3
bundle exec rake test:postgresql
bundle exec rake test:mysql2
bundle exec rake test:trilogy

You'll need a running database for the non-SQLite tasks. PostgreSQL and MySQL credentials are read from activerecord/test/config.yml and config.example.yml.

Run everything

From the repo root:

rake test            # All non-isolated tests for every component
rake test:isolated   # Tests that need their own process
rake smoke           # Quick smoke test across all components

You can also run a single component's suite via:

rake actionview:test
rake activerecord:test

Linting

Rails uses RuboCop for Ruby style and a couple of small JS configs:

bundle exec rubocop                # Whole repo
bundle exec rubocop activerecord/  # Just one component

The configuration lives in .rubocop.yml. Common rules:

• Rails/AssertNot — prefer assert_not over assert !
• # frozen_string_literal: true is required at the top of every Ruby file
• Markdown is checked by mdl against .mdlrc.rb
• JavaScript files (mostly in actioncable, activestorage, actiontext) are linted with ESLint via eslint.config.mjs

Generating documentation

Each component has a Rakefile target for generating its RDoc/YARD docs:

cd actionview && rake rdoc

The Rails Guides are built from guides/source/*.md. See guides/Rakefile and guides/source/api_documentation_guidelines.md.

Building a Rails application from your local checkout

To test a fix end-to-end against a real app, point a generated app at your local Rails:

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

The --dev flag rewrites the app's Gemfile to use path: references back to your checkout, so changes you make to the framework code are immediately visible.

Next steps

• How to contribute covers the full PR workflow.
• Patterns and conventions documents the code style that spans every component.
• Tooling describes the test runner, RuboCop config, and CI.