Skip to content

Add GitHub Copilot instructions for repository context #8917

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tagliala merged 6 commits into from
Jan 16, 2026
Merged

Add GitHub Copilot instructions for repository context #8917

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d4d9fb4
Add GitHub Copilot instructions file
Copilot Jan 14, 2026
6a7057b
Fix inaccuracies in Copilot instructions based on code review
Copilot Jan 14, 2026
942b3e2
Add RuboCop requirement to Copilot instructions
Copilot Jan 14, 2026
e677974
Update .github/copilot-instructions.md
tagliala Jan 16, 2026
a3d421d
Update .github/copilot-instructions.md
tagliala Jan 16, 2026
27fbdc3
Prefer RSpec specs over Cucumber features in test guidelines
Copilot Jan 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 114 additions & 0 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
# Active Admin - GitHub Copilot Instructions

## Project Overview

Active 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.

## Technology Stack

- **Backend**: Ruby on Rails (currently Rails ~> 8.1.0)
- **Frontend**: JavaScript (ES6+), Tailwind CSS, Flowbite
- **Testing**: RSpec (unit tests), Cucumber (feature tests), Capybara (integration tests)
- **Build Tools**: Rollup (JavaScript bundling), cssbundling-rails
- **Key Dependencies**: Devise (authentication), Ransack (search), Formtastic (forms), Kaminari (pagination)

## Ruby Conventions

- Minimum Ruby version: 3.2+ (required)
- Minimum Rails version: 7.2+ (required by gemspec)
- Current development uses Rails ~> 8.1.0
- Follow RuboCop style guide (configuration in `.rubocop.yml`)
- RuboCop plugins enabled: capybara, packaging, performance, rails, rspec
- Use frozen string literals: `# frozen_string_literal: true` at the top of Ruby files

## JavaScript Conventions

- Use ES6+ modern JavaScript syntax
- Follow ESLint configuration (see `eslint.config.js`)
- JavaScript source files are in `app/javascript/`
- Build JavaScript with: `npm run build`
- Lint JavaScript with: `npm run lint`

## Testing Guidelines

### Ruby Tests (RSpec)
- Unit tests are in `spec/unit/`
- Request specs are in `spec/requests/`
- Helper specs are in `spec/helpers/`
- Run RSpec tests: `bundle exec rspec`

### Feature Tests (Cucumber)
- Cucumber features are in `features/`
- Uses Capybara with Cuprite (headless Chrome)
- Cucumber scenarios require Chrome to be installed
- Run Cucumber tests: `bundle exec cucumber`
- Lint Gherkin files: `npm run gherkin-lint`

### Running All Tests
- Run the complete test suite: `bin/rake`
- Tests run against a sample Rails app generated in `tmp/test_apps/`

## Building and Development

### Setup
```bash
bundle install
yarn install
```

Note: The `bin/rake local server` command requires foreman, which it will invoke automatically. Install with `gem install foreman` if needed.

### Testing Against Different Rails Versions
```bash
# Available versions: rails_72, rails_80
export BUNDLE_GEMFILE=gemfiles/rails_72/Gemfile
```

### Local Development Server
```bash
bin/rake local server
# Visit http://localhost:3000/admin
# Login: admin@example.com / password
```

### Other Local Commands
```bash
bin/rake local console # Rails console
bin/rake local db:migrate # Run migrations
```

## Code Organization

- `lib/active_admin/` - Core framework code
- `app/` - Rails application components (controllers, helpers, views, assets)
- `spec/` - RSpec tests
- `features/` - Cucumber feature tests
- `docs/` - VitePress documentation (run with `npm run docs:dev`)

## Important Guidelines

1. **Minimal Changes**: Make surgical, precise changes. Don't refactor unrelated code.
2. **Backward Compatibility**: Active Admin is a widely-used gem. Maintain backward compatibility unless explicitly breaking changes are intended.
3. **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.
4. **Documentation**: Update documentation in `docs/` if adding user-facing features.
5. **Internationalization**: Support i18n - translation files are in `config/locales/`
6. **Security**: This is an administration framework so be extra cautious with security implications.
7. **Code Quality**: Always run `bundle exec rubocop` before submitting any PR to ensure code follows project style guidelines.

## Contributing Workflow

1. Create feature request discussion before starting significant new features
2. Fork and create a descriptive branch
3. Ensure tests pass: `bin/rake`
4. Run linting: `bundle exec rubocop` for Ruby code, `npm run lint` for JavaScript
5. View changes in browser: `bin/rake local server`
6. Submit pull request with passing CI

## Additional Context

- This is both a Ruby gem and an npm package
- Published to RubyGems as `activeadmin`
- Published to npm as `@activeadmin/activeadmin`
- The project uses both Ruby and JavaScript tooling
- CI runs tests against multiple Rails versions
- Code coverage tracked with SimpleCov and CodeCov