4.7 KiB
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
bun 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
bun run build # Build JavaScript with esbuild
bun run 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: trueat 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: disabledMetrics/MethodLength: max 30Style/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 (
.slimextension) - Use Foundation CSS framework
- Use Turbo/Hotwire for SPA-like behavior
Models
- Inherit from
ApplicationRecord - Use Shrine for file attachments (not Paperclip)
- Use
pg_searchfor 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_fromin controllers for handled exceptions - Use
Rails.logger.errorfor logging - Use custom exceptions in
lib/for domain errors
Authentication/Authorization
- Uses Devise for authentication
- Uses CanCanCan for authorization (see
Abilitymodel) - OAuth via OmniAuth with
omniauth_openid_connectfor 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