From 4e0858ccbe529c700c290d4d613e1472836afd78 Mon Sep 17 00:00:00 2001 From: Christoph Haas Date: Tue, 24 Feb 2026 23:59:56 +0100 Subject: [PATCH] Add AGENTS.md for AI agent guidance --- AGENTS.md | 175 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..69fec66 --- /dev/null +++ b/AGENTS.md @@ -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