debshots/AGENTS.md

4.7 KiB

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

bundle install              # Install Ruby dependencies
yarn install               # Install JavaScript dependencies
rails db:create db:migrate # Create and migrate database

Development

bin/dev                    # Start development server (runs foreman)
rails server               # Alternative: start Rails server
rails console              # Open Rails console

Testing

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

rubocop                    # Run RuboCop linter
rubocop -a                 # Auto-fix RuboCop offenses

Frontend Build

yarn build                # Build JavaScript with esbuild
yarn build:css            # Build CSS with Sass

Database

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

rails generate model User name:string email:string
rails db:migrate

Generate a controller

rails generate controller Admin

Run a specific rake task

rails rake namespace:task_name

Create admin user

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