Add AGENTS.md for AI agent guidance
This commit is contained in:
parent
54d607ce23
commit
4e0858ccbe
1 changed files with 175 additions and 0 deletions
175
AGENTS.md
Normal file
175
AGENTS.md
Normal file
|
|
@ -0,0 +1,175 @@
|
||||||
|
# AGENTS.md - Debshots Development Guide
|
||||||
|
|
||||||
|
This file provides guidance for AI agents working in the debshots codebase.
|
||||||
|
|
||||||
|
## Project Overview
|
||||||
|
|
||||||
|
Debshots is a Ruby on Rails 8 application that powers screenshots.debian.net. It provides package screenshots for Debian/Ubuntu package managers.
|
||||||
|
|
||||||
|
## Build/Lint/Test Commands
|
||||||
|
|
||||||
|
### Setup
|
||||||
|
```bash
|
||||||
|
bundle install # Install Ruby dependencies
|
||||||
|
yarn install # Install JavaScript dependencies
|
||||||
|
rails db:create db:migrate # Create and migrate database
|
||||||
|
```
|
||||||
|
|
||||||
|
### Development
|
||||||
|
```bash
|
||||||
|
bin/dev # Start development server (runs foreman)
|
||||||
|
rails server # Alternative: start Rails server
|
||||||
|
rails console # Open Rails console
|
||||||
|
```
|
||||||
|
|
||||||
|
### Testing
|
||||||
|
```bash
|
||||||
|
rails test # Run all tests
|
||||||
|
rails test test/models/screenshot_test.rb # Run single test file
|
||||||
|
rails test -n test_name # Run single test method
|
||||||
|
rails test test/models/ test/controllers/ # Run tests in directory
|
||||||
|
```
|
||||||
|
|
||||||
|
### Linting
|
||||||
|
```bash
|
||||||
|
rubocop # Run RuboCop linter
|
||||||
|
rubocop -a # Auto-fix RuboCop offenses
|
||||||
|
```
|
||||||
|
|
||||||
|
### Frontend Build
|
||||||
|
```bash
|
||||||
|
yarn build # Build JavaScript with esbuild
|
||||||
|
yarn build:css # Build CSS with Sass
|
||||||
|
```
|
||||||
|
|
||||||
|
### Database
|
||||||
|
```bash
|
||||||
|
rails db:migrate # Run migrations
|
||||||
|
rails db:rollback # Rollback last migration
|
||||||
|
rails db:reset # Reset database
|
||||||
|
rails db:seed # Seed database
|
||||||
|
```
|
||||||
|
|
||||||
|
## Code Style Guidelines
|
||||||
|
|
||||||
|
### General
|
||||||
|
- Ruby version: 3.x
|
||||||
|
- Rails version: 8.x
|
||||||
|
- Always use `frozen_string_literal: true` at the top of Ruby files
|
||||||
|
|
||||||
|
### Naming Conventions
|
||||||
|
- **Files**: snake_case (e.g., `user_session.rb`)
|
||||||
|
- **Classes/Modules**: CamelCase (e.g., `UserSession`)
|
||||||
|
- **Methods/variables**: snake_case (e.g., `user_name`, `active_user?`)
|
||||||
|
- **Database columns**: snake_case (e.g., `created_at`, `user_id`)
|
||||||
|
- **Constants**: SCREAMING_SNAKE_CASE
|
||||||
|
|
||||||
|
### RuboCop Configuration
|
||||||
|
The project uses `rubocop-rails-omakase` with these overrides in `.rubocop.yml`:
|
||||||
|
- Line length: max 99 characters
|
||||||
|
- Encoding: disabled
|
||||||
|
- `Lint/MixedRegexpCaptureTypes`: disabled
|
||||||
|
- `Metrics/MethodLength`: max 30
|
||||||
|
- `Style/IfUnlessModifier`: disabled
|
||||||
|
|
||||||
|
### Formatting
|
||||||
|
- Use 2 spaces for indentation (no tabs)
|
||||||
|
- Use single-quoted strings unless interpolation needed
|
||||||
|
- Use `%w[]` for word arrays
|
||||||
|
- Use `%i[]` for symbol arrays
|
||||||
|
|
||||||
|
### Imports/Dependencies
|
||||||
|
- Prefer standard Rails patterns over explicit requires
|
||||||
|
- Gemfile groups: `:development`, `:test`, `:development, :test`
|
||||||
|
|
||||||
|
### Views
|
||||||
|
- Use Slim templates (`.slim` extension)
|
||||||
|
- Use Foundation CSS framework
|
||||||
|
- Use Turbo/Hotwire for SPA-like behavior
|
||||||
|
|
||||||
|
### Models
|
||||||
|
- Inherit from `ApplicationRecord`
|
||||||
|
- Use Shrine for file attachments (not Paperclip)
|
||||||
|
- Use `pg_search` for PostgreSQL full-text search
|
||||||
|
|
||||||
|
### Controllers
|
||||||
|
- Inherit from `ApplicationController`
|
||||||
|
- Use strong parameters
|
||||||
|
- Follow RESTful routing
|
||||||
|
|
||||||
|
### Testing
|
||||||
|
- Uses Minitest (not RSpec)
|
||||||
|
- Fixtures in `test/fixtures/*.yml`
|
||||||
|
- System tests use Capybara with Selenium
|
||||||
|
- Devise test helpers available via `Devise::Test::ControllerHelpers`
|
||||||
|
|
||||||
|
### Error Handling
|
||||||
|
- Use `rescue_from` in controllers for handled exceptions
|
||||||
|
- Use `Rails.logger.error` for logging
|
||||||
|
- Use custom exceptions in `lib/` for domain errors
|
||||||
|
|
||||||
|
### Authentication/Authorization
|
||||||
|
- Uses Devise for authentication
|
||||||
|
- Uses CanCanCan for authorization (see `Ability` model)
|
||||||
|
- OAuth via OmniAuth with `omniauth_openid_connect` for salsa.debian.net
|
||||||
|
|
||||||
|
### Key Gems
|
||||||
|
- **File uploads**: Shrine
|
||||||
|
- **Auth**: Devise + OmniAuth
|
||||||
|
- **AuthZ**: CanCanCan
|
||||||
|
- **Images**: MiniMagick, ImageProcessing
|
||||||
|
- **DB**: PostgreSQL + pg_search
|
||||||
|
- **Search**: Full-text via pg_search
|
||||||
|
|
||||||
|
## File Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
app/
|
||||||
|
controllers/ # Rails controllers
|
||||||
|
models/ # ActiveRecord models
|
||||||
|
views/ # Slim templates
|
||||||
|
helpers/ # View helpers
|
||||||
|
assets/ # JS/CSS/images
|
||||||
|
config/
|
||||||
|
environments/ # Environment configs
|
||||||
|
routes.rb # Routing
|
||||||
|
db/
|
||||||
|
migrate/ # Migrations
|
||||||
|
schema.rb # Schema
|
||||||
|
lib/ # Library code
|
||||||
|
test/ # Minitest tests
|
||||||
|
models/ # Model tests
|
||||||
|
controllers/ # Controller tests
|
||||||
|
system/ # System/feature tests
|
||||||
|
fixtures/ # Test fixtures
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Tasks
|
||||||
|
|
||||||
|
### Generate a model
|
||||||
|
```bash
|
||||||
|
rails generate model User name:string email:string
|
||||||
|
rails db:migrate
|
||||||
|
```
|
||||||
|
|
||||||
|
### Generate a controller
|
||||||
|
```bash
|
||||||
|
rails generate controller Admin
|
||||||
|
```
|
||||||
|
|
||||||
|
### Run a specific rake task
|
||||||
|
```bash
|
||||||
|
rails rake namespace:task_name
|
||||||
|
```
|
||||||
|
|
||||||
|
### Create admin user
|
||||||
|
```bash
|
||||||
|
rails console
|
||||||
|
User.new(email: 'admin@example.com', password: 'secret').save
|
||||||
|
```
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- Application uses Docker for deployment (see Dockerfile, docker-compose.yml)
|
||||||
|
- CI uses Woodpecker (see `.woodpecker.yml`)
|
||||||
|
- Legacy: Previously used Paperclip, migrated to Shrine
|
||||||
Loading…
Add table
Add a link
Reference in a new issue