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, development standards, integration test reference, review checklist, and Bruno collection guidelines that all contributions must follow.

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.3 KiB Raw Blame History