Copilot instructions

1# Active Admin - GitHub Copilot Instructions
2 
3## Project Overview
4 
5Active Admin is a Ruby on Rails framework for creating elegant backends for website administration. It provides a DSL for developers to quickly create good-looking administration interfaces.
6 
7## Technology Stack
8 
9- **Backend**: Ruby on Rails (currently Rails ~> 8.1.0)
10- **Frontend**: JavaScript (ES6+), Tailwind CSS, Flowbite
11- **Testing**: RSpec (unit tests), Cucumber (feature tests), Capybara (integration tests)
12- **Build Tools**: Rollup (JavaScript bundling), cssbundling-rails
13- **Key Dependencies**: Devise (authentication), Ransack (search), Formtastic (forms), Kaminari (pagination)
14 
15## Ruby Conventions
16 
17- Minimum Ruby version: 3.3+ (required)
18- Minimum Rails version: 7.2+ (required by gemspec)
19- Current development uses Rails ~> 8.1.0
20- Follow RuboCop style guide (configuration in `.rubocop.yml`)
21- RuboCop plugins enabled: capybara, packaging, performance, rails, rspec
22- Use frozen string literals: `# frozen_string_literal: true` at the top of Ruby files
23 
24## JavaScript Conventions
25 
26- Use ES6+ modern JavaScript syntax
27- Follow ESLint configuration (see `eslint.config.js`)
28- JavaScript source files are in `app/javascript/`
29- Build JavaScript with: `npm run build`
30- Lint JavaScript with: `npm run lint`
31 
32## Testing Guidelines
33 
34### Ruby Tests (RSpec)
35- Unit tests are in `spec/unit/`
36- Request specs are in `spec/requests/`
37- Helper specs are in `spec/helpers/`
38- Run RSpec tests: `bundle exec rspec`
39 
40### Feature Tests (Cucumber)
41- Cucumber features are in `features/`
42- Uses Capybara with Cuprite (headless Chrome)
43- Cucumber scenarios require Chrome to be installed
44- Run Cucumber tests: `bundle exec cucumber`
45- Lint Gherkin files: `npm run gherkin-lint`
46 
47### Running All Tests
48- Run the complete test suite: `bin/rake`
49- Tests run against a sample Rails app generated in `tmp/test_apps/`
50 
51## Building and Development
52 
53### Setup
54```bash
55bundle install
56yarn install
57```
58 
59Note: The `bin/rake local server` command requires foreman, which it will invoke automatically. Install with `gem install foreman` if needed.
60 
61### Testing Against Different Rails Versions
62```bash
63# Available versions: rails_72, rails_80
64export BUNDLE_GEMFILE=gemfiles/rails_72/Gemfile
65```
66 
67### Local Development Server
68```bash
69bin/rake local server
70# Visit http://localhost:3000/admin
71# Login: admin@example.com / password
72```
73 
74### Other Local Commands
75```bash
76bin/rake local console      # Rails console
77bin/rake local db:migrate   # Run migrations
78```
79 
80## Code Organization
81 
82- `lib/active_admin/` - Core framework code
83- `app/` - Rails application components (controllers, helpers, views, assets)
84- `spec/` - RSpec tests
85- `features/` - Cucumber feature tests
86- `docs/` - VitePress documentation (run with `npm run docs:dev`)
87 
88## Important Guidelines
89 
901. **Minimal Changes**: Make surgical, precise changes. Don't refactor unrelated code.
912. **Backward Compatibility**: Active Admin is a widely-used gem. Maintain backward compatibility unless explicitly breaking changes are intended.
923. **Test Coverage**: Include tests for new features. Prefer RSpec specs (especially request specs) over Cucumber features when possible, as specs are easier to work with and maintain.
934. **Documentation**: Update documentation in `docs/` if adding user-facing features.
945. **Internationalization**: Support i18n - translation files are in `config/locales/`
956. **Security**: This is an administration framework so be extra cautious with security implications.
967. **Code Quality**: Always run ALL relevant linters before submitting any PR to ensure code follows project style guidelines:
97   - Ruby code: `bundle exec rubocop`
98   - JavaScript code: `npm run lint`
99   - Gherkin files: `npm run gherkin-lint`
100   - Run these linters BEFORE requesting code review or submitting the PR.
101 
102## Contributing Workflow
103 
1041. Create feature request discussion before starting significant new features
1052. Fork and create a descriptive branch
1063. Ensure tests pass: `bin/rake`
1074. **Run ALL linters BEFORE submitting PR**:
108   - Ruby code: `bundle exec rubocop`
109   - JavaScript code: `npm run lint`
110   - Gherkin files: `npm run gherkin-lint`
1115. View changes in browser: `bin/rake local server`
1126. Submit pull request with passing CI
113 
114## Commit Message Guidelines
115 
116Follow the project's commit message standards as outlined in [CONTRIBUTING.md](../CONTRIBUTING.md):
117 
118### Format Requirements
119- **Reference**: Follow [How to Write a Git Commit Message](https://cbea.ms/git-commit/#seven-rules)
120- **Format**: Use imperative mood ("Add feature" not "Added feature")
121- **Length**: Limit subject line to 50 characters, body lines to 72 characters
122- **Structure**:
123```
124  Short summary (50 chars max)
125 
126  Detailed explanation if needed (72 chars per line)
127 
128  - Use bullet points for multiple changes
129  - Reference issues with "Fixes #123" or "Closes #456"
130```
131 
132### Commit Message Examples
133```
134Fix temporal query performance regression
135 
136Add support for Rails 8.0 compatibility
137 
138Update dependencies for security patches
139 
140Fixes #123
141```
142 
143### Best Practices
144- Keep commits atomic (one logical change per commit)
145- Write clear, descriptive commit messages
146- Reference related issues and pull requests
147- Avoid generic messages like "Fix bug" or "Update code"
148 
149## Additional Context
150 
151- This is both a Ruby gem and an npm package
152- Published to RubyGems as `activeadmin`
153- Published to npm as `@activeadmin/activeadmin`
154- The project uses both Ruby and JavaScript tooling
155- CI runs tests against multiple Rails versions
156- Code coverage tracked with SimpleCov and CodeCov
157