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