# 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