AGENTS.md

1# Ruby on Rails Codebase Guide for AI Coding Agents
2 
3This is the code base of the Ruby on Rails web framework.
4 
5## Architecture Overview
6 
7Rails is a **monorepo containing 10+ independent components** that can work standalone or together.
8 
9Each component lives in its own directory at the root level:
10 
11- **Active Record** (`activerecord/`) - ORM and database abstraction
12- **Action Pack** (`actionpack/`) - Controllers and routing (contains Action Controller and Action Dispatch)
13- **Action View** (`actionview/`) - View templates and helpers (extracted from Action Pack in Rails 3)
14- **Active Model** (`activemodel/`) - Model interfaces without database dependency
15- **Active Support** (`activesupport/`) - Core extensions and utilities used across all Rails components
16- **Action Mailer** (`actionmailer/`), **Action Mailbox** (`actionmailbox/`) - Email sending/receiving
17- **Active Job** (`activejob/`) - Background job abstraction
18- **Action Cable** (`actioncable/`) - WebSocket integration
19- **Active Storage** (`activestorage/`) - File uploads and cloud storage
20- **Action Text** (`actiontext/`) - Rich text content
21- **Railties** (`railties/`) - Rails CLI, generators, and framework glue
22 
23**Key architectural principle**: Rails components are loosely coupled. Changes to one of them should not break others unless there's an explicit dependency.
24 
25## Testing Commands
26 
27### Running Tests in a Component
28 
29From within the component directory (preferred method):
30 
31```bash
32cd actionview && bin/test                    # Run all tests
33cd actionview && bin/test test/template/form_helper_test.rb
34cd actionview && bin/test -i "/test_name/"   # Filter by test name pattern
35```
36 
37How to run a specific test method:
38 
39```bash
40cd actionview && bin/test test/template/form_helper_test.rb -i test_hidden_field
41```
42 
43How to run the test at a specific line:
44 
45```bash
46cd actionview && bin/test test/template/form_helper_test.rb:123
47```
48 
49### Running Tests from Root
50 
51Run all tests for a given component:
52 
53```bash
54rake actionview:test
55```
56 
57Run tests across all components:
58 
59```bash
60rake test          # Run all tests
61rake smoke         # Quick smoke test
62```
63 
64### Active Record Testing (Multiple Database Adapters)
65 
66How to test individual database adapters in Active Record:
67 
68```bash
69cd activerecord
70bundle exec rake test:sqlite3 # Default
71bundle exec rake test:postgresql
72bundle exec rake test:mysql2
73bundle exec rake test:trilogy
74```
75 
76**Important**: Tests run in parallel using multiple processes. The `bin/test` script wraps Rails' custom test runner (`tools/test.rb`) which uses `Rails::TestUnit::Runner`.
77 
78## Configuration Testing Patterns
79 
80When testing configuration options, use `Object#with` (from Active Support) to temporarily modify class attributes:
81 
82```ruby
83# Correct: Use Object#with for temporary config changes
84ActionView::Base.with(remove_hidden_field_autocomplete: true) do
85  # Test code here
86end
87 
88# Avoid: Manual set/restore patterns
89old = ActionView::Base.remove_hidden_field_autocomplete
90ActionView::Base.remove_hidden_field_autocomplete = true
91# ... test code
92ActionView::Base.remove_hidden_field_autocomplete = old
93```
94 
95This pattern is used throughout the test suite, especially for:
96 
97- `ActionView::Base.with(config_option: value)`
98- `ActionController::Base.with(config_option: value)`
99- Other framework configuration testing
100 
101**Requires**: `require "active_support/core_ext/object/with"` at the top of test files.
102 
103## Code Conventions
104 
105### Configuration Flags
106 
107Configuration options follow a consistent pattern across components:
108 
1091. **Define the attribute** in the base class (e.g., `ActionView::Base`):
110```ruby
111   cattr_accessor :remove_hidden_field_autocomplete, default: false
112```
113 
1142. **Check the flag** before applying behavior:
115```ruby
116   @options.reverse_merge!(autocomplete: "off") unless ActionView::Base.remove_hidden_field_autocomplete
117```
118 
1193. **Enable by default** in new Rails versions via `load_defaults`:
120```ruby
121   # In railties/lib/rails/application/configuration.rb
122   case target_version.to_s
123   when "8.1"
124     action_view.remove_hidden_field_autocomplete = true
125   end
126```
127 
128### Changelog Updates
129 
130When fixing bugs or adding features:
131 
132- Add an entry to the top of `<component>/CHANGELOG.md`
133- Format: Brief description, then `*Your Name*` on new line
134- See existing entries for style
135 
136### Test Naming
137 
138- Use descriptive names: `test_hidden_field_omits_autocomplete_when_remove_hidden_field_autocomplete_is_true`
139- Group related tests together in the file
140- Test both default behavior AND explicit overrides
141 
142### Code Style
143 
144- Run RuboCop: `bundle exec rubocop` (there's a project-wide `.rubocop.yml`)
145- Prefer `assert_not` over `assert !` (`Rails/AssertNot` cop)
146- Prefer `assert_dom_equal` for HTML comparisons in view tests
147- Use `# frozen_string_literal: true` at top of all files
148 
149## Common Development Workflows
150 
151### Making a Fix Across Multiple Components
152 
153Example: Issue #55984 required changes to:
154 
1551. Helper class: `actionview/lib/action_view/helpers/tags/hidden_field.rb`
1562. Tests: `actionview/test/template/form_helper_test.rb`
1573. Reference: Similar fixes were in `tags/check_box.rb`, `tags/file_field.rb`, `form_tag_helper.rb`, `url_helper.rb`
158 
159**Pattern**: When fixing a configuration flag, grep for similar patterns in other helpers:
160 
161```bash
162grep -r &quot;unless ActionView::Base.remove_hidden_field_autocomplete&quot; actionview/lib/
163```
164 
165### Finding Related Code
166 
167- **Similar functionality**: Look in the same `lib/*/helpers/` or `lib/*/tags/` directory
168- **Tests for a helper**: Check `test/template/<helper_name>_test.rb`
169- **Configuration setup**: Check `railties/lib/rails/application/configuration.rb`
170- **Default values**: Look for `load_defaults` version blocks
171 
172### Working with Forms and Helpers
173 
174Action View helpers follow this structure:
175 
176- **Tag helpers** (`lib/action_view/helpers/tags/`) - Individual form elements
177- **Form helpers** (`lib/action_view/helpers/form_helper.rb`) - Form builders
178- **Form tag helpers** (`lib/action_view/helpers/form_tag_helper.rb`) - Standalone tags
179 
180When modifying form behavior, check ALL three locations for consistency.
181 
182## Issue References and Pull Requests
183 
184- Always reference issue numbers in commits: `Fix #12345: Description`
185- Check for previous related PRs/issues when fixing bugs
186- Bug report templates live in `guides/bug_report_templates/`
187 
188## File Organization Principles
189 
190- `lib/` - Production code
191- `test/` - Test files (NOT `spec/` - Rails uses Minitest, not RSpec)
192- `bin/` - Executable scripts (e.g., `bin/test`)
193- Each framework is self-contained with its own Gemfile and dependencies
194- Shared tools live in `tools/` (e.g., `tools/test.rb`, `tools/release.rb`)
195 
196## Documentation
197 
198- API docs use YARD/RDoc format
199- Guides source in `guides/source/` (Markdown)
200- Generate docs: `rake rdoc` (from framework directory)
201- Configuration options documented in `guides/source/configuring.md`
202