gotenberg/AGENTS.md

Operational Guidelines for Gotenberg

As an AI agent working on the Gotenberg repository, you are expected to act with the diligence and architectural foresight of a Senior Go Engineer. Gotenberg is a widely used production dependency; stability and backward compatibility are paramount.

1. Core Philosophy & Stability

• Backward Compatibility is Law: This project creates a public API. Never modify existing flags, configuration environment variables, or API form fields unless explicitly instructed to perform a breaking change. If a change is breaking, it must be flagged immediately in the plan.
• Defensive Programming: Assume input data is malformed. Handle errors explicitly. Do not panic.
• Atomic Commits: Isolate refactoring from feature additions. A Pull Request should do one thing well.

2. Development Workflow & Tooling

You must rely strictly on the project's Makefile for build and verification tasks. Do not run go commands directly unless debugging a specific package requires it.

• Formatting: Run make fmt to format Go code before committing.
• Linting:
  • Run make lint to ensure Go code strictly adheres to the .golangci.yml configuration.
  • Run make lint-prettier to verify formatting for non-Go files (Markdown, YAML, etc.).
  • Zero linting errors are permitted.
• Building: Run make build to verify compilation and Docker image construction.

3. Architecture & Code Structure

• Idiomatic Go: Follow "Effective Go" principles.
• Directory Separation:
  • cmd/: Application entry points only. Contains wiring and startup logic. No business logic is permitted here.
  • pkg/: Core library code and modules. All business logic resides here.
• Module System: Gotenberg is modular (e.g., Chromium, LibreOffice). When adding features, determine if they belong to an existing module or require a new strict isolation.

4. Testing Standards

Gotenberg utilizes a split testing strategy. Integration tests are the primary and preferred method for verifying features.

• Integration Tests (make test-integration):
  • First Priority: Always start here when adding features or routes.
  • Gotenberg uses Gherkin (Godog) for end-to-end verification.
  • You must create or update the corresponding .feature file in test/integration.
  • These tests run within the Docker context; ensure environment consistency.
• Unit Tests (make test-unit):
  • Use table-driven tests for pure logic within pkg/.
  • Mock external dependencies (filesystem, network) where appropriate.

5. Documentation Requirements

• No README Updates: Do not modify the root README.md unless explicitly asked.
• GoDoc is Mandatory:
  • New Packages: If creating a new package, you must include a doc.go file containing the package-level documentation.
  • Exported Symbols: Every exported function, type, constant, and variable must have a proper GoDoc comment starting with its name.
  • Quality: Comments must be complete sentences explaining what the symbol does and how to use it.
  • Example:

    // Convert transforms the input document to PDF using the Chromium engine.
    // It returns an error if the connection to the browser instance fails.
    func Convert(...) error
    

6. Definition of Done

A task is considered complete only when:

1. The code compiles via make build.
2. The code is formatted via make fmt.
3. All linters pass via make lint and make lint-prettier.
4. Integration scenarios pass via make test-integration.
5. Unit tests pass via make test-unit.
6. All exported symbols and new packages have compliant GoDoc.