Contributing to Gotenberg

Thank you for your interest in contributing to Gotenberg! This guide will help you get started.

Getting Started

Prerequisites

Go (see version in go.mod)
Docker
Node.js (see version in .node-version) — for Prettier linting
golangci-lint v2+

Build and Run

make build # Build the Docker image
make run   # Run a local Gotenberg container

Development Loop

# Write your code, then:
make fmt              # Format Go code
make prettify         # Format non-Go files (Markdown, YAML, etc.)
make lint             # Lint Go code (zero errors permitted)
make lint-prettier    # Lint non-Go files
make test-unit        # Run unit tests
make build            # Build the Docker image (required before integration tests)
make test-integration # Run all integration tests
make telemetry        # Start OpenTelemetry collector and OpenObserve
make down             # Stop all compose containers

To run only the integration tests relevant to your change:

make test-integration TAGS=health
make test-integration TAGS=chromium-convert-html
make test-integration TAGS="merge,split"

Submitting a Pull Request

Before opening a PR, verify:

Code compiles: make build
Code is formatted: make fmt and make prettify
All linters pass: make lint and make lint-prettier
Integration tests pass: make test-integration (at minimum, the relevant tags)
Unit tests pass: make test-unit
All exported symbols and new packages have GoDoc comments

Guidelines

Conventional Commits. Commit messages must follow the Conventional Commits specification (e.g., feat(chromium): add screenshot endpoint, fix(api): handle empty body).
One thing per PR. Keep features, bug fixes, and refactoring in separate PRs.
Backward compatibility matters. Do not rename or remove existing CLI flags, environment variables, or API form fields without discussion.
Integration tests first. When adding a feature or route, start by writing the Gherkin scenario in test/integration/features/.
Logging uses gotenberg.Logger(mod) with context-aware calls (*Context variants).
External operations have OTEL traces with appropriate SpanKind and semconv attributes.
No business logic in cmd/. All logic belongs in pkg/.

Detailed Guidelines

The AGENTS.md files contain comprehensive guidelines used by both human contributors and AI-assisted tools:

File	What it covers
`AGENTS.md`	Core principles, mandatory workflow, project layout, coding patterns, module system, Makefile reference, review checklist
`test/integration/AGENTS.md`	Integration test framework (Godog/Gherkin), available tags, step reference, how to write new tests
`.bruno/AGENTS.md`	Bruno API collection structure, `.bru` file format, conventions, route update checklist
`pkg/modules/pdfengines/AGENTS.md`	How to add new PDF engine features (Makefile variable and flag)

3.7 KiB Raw Blame History