Contributing to Gotenberg

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

Before You Start

Please read the AGENTS.md file — it describes the core principles, project layout, and development standards that all contributions must follow. Even though it is written for AI agents, the same rules apply to human contributors.

For deeper context on specific areas, see the personas in .agents/:

DEVELOPER — Makefile workflow, module system, coding patterns.
TESTER — How to write integration and unit tests.
REVIEWER — What reviewers look for (useful to check before submitting).

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

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/.
No business logic in cmd/. All logic belongs in pkg/.

2.7 KiB Raw Blame History