invisi/gotenberg
1
0
Fork 0
mirror of https://github.com/gotenberg/gotenberg.git synced 2026-07-02 00:17:40 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(contributing): reorganize sections and slim PR checklist

Browse Source
This commit is contained in:
Julien Neuhart
2026-04-30 15:14:03 +02:00
parent 8c0ad887f2
commit b47b9f45d8
1 changed files with 74 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+74 -86
View File
@@ -1,6 +1,11 @@
# Contributing to Gotenberg
Gotenberg is a Docker-based API for converting documents to PDF. Two rules override everything else: **backward compatibility** (never rename or remove CLI flags, environment variables, API form fields, or HTTP endpoints without discussion) and **defensive programming** (assume input is malformed, handle errors explicitly, never panic).
Gotenberg is a Docker-based API for converting documents to PDF. Two rules override everything else:
- **Backward compatibility.** Never rename or remove CLI flags, environment variables, API form fields, or HTTP endpoints without discussion.
- **Defensive programming.** Assume input is malformed, handle errors explicitly, never panic.
## Toolchain
- Module: `github.com/gotenberg/gotenberg/v8`
- Go: see version in `go.mod`
@@ -8,38 +13,13 @@ Gotenberg is a Docker-based API for converting documents to PDF. Two rules overr
- Node.js (see `.node-version`), for Prettier linting
- [golangci-lint](https://golangci-lint.run/) v2+
## Quick start
## Before you start
```bash
make build # Build the Docker image
make run # Run a local Gotenberg container
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 # Required before integration tests
make test-integration # Run all integration tests
make telemetry # Start OpenTelemetry collector and OpenObserve
make down # Stop all compose containers
```
For non-trivial changes, open an issue or a draft PR first. Describe what needs to change, the proposed solution (files to modify, interface changes, form fields), and which integration test tags are affected.
Run only the integration tests relevant to your change:
One thing per PR. Keep features, bug fixes, and refactoring in separate PRs.
```bash
make test-integration TAGS=health
make test-integration TAGS=chromium-convert-html
make test-integration TAGS="merge,split"
```
All build and verification tasks go through the Makefile. Do not run `go` commands directly unless debugging a specific package.
| Command | Purpose | When to use |
| ---------------- | --------------------------------------------- | ------------------------------------------------------------------------ |
| `make run` | Run Gotenberg container via `docker compose` | Manual testing. Flags configured via Makefile variables and compose.yaml |
| `make telemetry` | Start OpenTelemetry collector and OpenObserve | When testing telemetry locally |
| `make down` | Stop all compose containers | After manual testing |
| `make godoc` | Serve GoDoc at `localhost:6060` | To verify documentation |
When adding a feature or route, write the Gherkin scenario before the Go code, and plan to update the Bruno collection (`.bruno/`) if a route changes.
## Project layout
@@ -53,9 +33,35 @@ build/ -> Dockerfile, fonts, Chromium config.
.bruno/ -> Bruno API collection (mirrors every route).
```
Key interfaces live in `pkg/gotenberg/`: `Module`, `Provisioner`, `Validator`, `Debuggable`. Every module implements `Descriptor()` and self-registers.
Key interfaces live in `pkg/gotenberg/`: `Module`, `Provisioner`, `Validator`, `Debuggable`. Every module implements `Descriptor()` and self-registers via `init()`.
## Coding rules
## Setup and Makefile
All build and verification tasks go through the Makefile. Do not run `go` commands directly unless debugging a specific package.
| Command | Purpose | When to use |
| ----------------------- | ------------------------------------------------ | ------------------------------------------------------------------------ |
| `make build` | Build the Gotenberg Docker image | Before integration tests or manual testing |
| `make run` | Run a Gotenberg container via `docker compose` | Manual testing. Flags configured via Makefile variables and compose.yaml |
| `make telemetry` | Start an OpenTelemetry collector and OpenObserve | When testing telemetry locally |
| `make down` | Stop all compose containers | After manual testing |
| `make godoc` | Serve GoDoc at `localhost:6060` | To verify documentation |
| `make fmt` | Format Go code | Before committing |
| `make lint` | Lint Go code (zero errors permitted) | Before committing |
| `make prettify` | Format non-Go files (Markdown, YAML, JSON) | Before committing |
| `make lint-prettier` | Lint non-Go files | Before committing |
| `make test-unit` | Run unit tests | Before committing |
| `make test-integration` | Run all integration tests (40 min timeout) | Before committing |
Run only the integration test tag(s) relevant to your change rather than the full suite:
```bash
make test-integration TAGS=health
make test-integration TAGS=chromium-convert-html
make test-integration TAGS="merge,split"
```
## Code conventions
### Module system
@@ -63,17 +69,21 @@ Gotenberg uses a self-registering module architecture inspired by CaddyServer. E
Determine if a feature belongs in an existing module before creating a new one. Only create a new module for a genuinely separate concern.
The `cmd/gotenberg/` package is strictly for wiring and startup. No business logic.
### Backward compatibility
CLI flags, environment variables, API form fields, HTTP endpoints, and default values that alter existing behavior must not change without discussion. Deprecate old names with `fs.MarkDeprecated()` and register both the old and new names side by side.
If a change violates backward compatibility, flag it as a breaking change in the PR description.
### Error handling
- Wrap every error with context: `fmt.Errorf("description: %w", err)`.
- Never swallow errors silently.
- Match errors with `errors.Is`, never `strings.Contains`.
- No panics in production code paths.
- Input is validated defensively.
### Import ordering
Enforced by `gci`: standard library, then third-party, then `github.com/gotenberg/gotenberg/v8`. Three groups separated by blank lines.
- Validate input defensively.
### Logging
@@ -83,15 +93,11 @@ Use `gotenberg.Logger(mod)` to get the module's slog logger during `Provision()`
External tool calls (Chromium, LibreOffice, PDF engines, webhooks, downloads) must create OTEL spans with `trace.SpanKindClient` and `semconv.ServerAddress("toolname")`. Use `gotenberg.Tracer()` and `gotenberg.Meter()` for traces and metrics.
### No business logic in `cmd/`
### Import ordering
The `cmd/gotenberg/` package is strictly for wiring and startup.
Enforced by `gci`: standard library, then third-party, then `github.com/gotenberg/gotenberg/v8`. Three groups separated by blank lines.
### Mocks
Comprehensive mock implementations for all major interfaces live in `pkg/gotenberg/mocks.go`. Use these for unit tests rather than creating new ones.
## Documentation rules
## Documentation conventions
### Tone
@@ -131,60 +137,42 @@ Reference identifiers with `[Name]` brackets for pkg.go.dev linking:
- Reference spec clauses where relevant (`// Per ISO 32000-2, Table 116...`).
- Mark debt with `// TODO: [context]`.
### Formatting non-Go files
Run `make prettify && make lint-prettier` for YAML, Markdown, and JSON.
## Testing
Integration tests use Gherkin (BDD) via Godog with `testcontainers-go` for Docker orchestration. Feature files live in `test/integration/features/`. Step definitions live in `test/integration/scenario/`. Read `scenario.go` and `containers.go` to understand step definitions before writing new tests.
### Unit tests
Unit tests: table-driven tests in `*_test.go` files using mocks from `pkg/gotenberg/mocks.go`.
Table-driven tests in `*_test.go` files. Use the comprehensive mock implementations in `pkg/gotenberg/mocks.go` rather than rolling new ones.
Run only the relevant integration test tag rather than the full suite (40min timeout).
### Integration tests
See:
Gherkin (BDD) via Godog with `testcontainers-go` for Docker orchestration. Feature files live in `test/integration/features/`; step definitions live in `test/integration/scenario/`. Read `scenario.go` and `containers.go` before writing new tests.
- [`test/integration/README.md`](test/integration/README.md): Gherkin step reference, available tags, writing new tests.
- [`.bruno/README.md`](.bruno/README.md): `.bru` file format, conventions, route update checklist.
- [`pkg/modules/pdfengines/README.md`](pkg/modules/pdfengines/README.md): adding new engine features (Makefile variable and flag).
`make build` is required before running integration tests. The full suite has a 40-minute timeout, so run only the tag(s) relevant to your change.
## Pull requests
Plan non-trivial changes before coding. Open an issue or draft PR describing what needs to change, the proposed solution (files to modify, interface changes, form fields), and which integration test tags are affected.
### Guidelines
- One thing per PR. Keep features, bug fixes, and refactoring separate.
- 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.
- Bruno collection must be updated if routes were added or modified.
### Checklist
- [ ] No existing CLI flags renamed or removed
- [ ] No existing environment variables renamed or removed
- [ ] No existing API form fields renamed or removed
- [ ] No existing HTTP endpoints changed or removed
- [ ] No changes to default values that alter existing behavior
- [ ] Deprecated flags have both old and new names registered, with `fs.MarkDeprecated()`
- [ ] Errors wrapped with context: `fmt.Errorf("description: %w", err)`
- [ ] No business logic in `cmd/`
- [ ] No panics in production code paths
- [ ] New features belong in the correct module (or justify a new one)
- [ ] Linting: `make fmt && make lint && make prettify && make lint-prettier` passes with zero warnings
- [ ] Every exported function, type, constant, and variable has a Godoc comment starting with its name
- [ ] New packages include a `doc.go` file
- [ ] Integration tests pass: `make test-integration` (at minimum, the relevant tags)
- [ ] Unit tests pass: `make test-unit`
- [ ] Bruno collection updated (if routes were added or modified)
If any backward compatibility item is violated, the change **must** be flagged as a breaking change.
### Commits
[Conventional Commits](https://www.conventionalcommits.org/): `<type>(<scope>): <description>`.
Common types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `ci`, `build`. The scope should match the module or area of the change (e.g., `chromium`, `pdfengines`, `api`).
Common types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `ci`, `build`. The scope matches the module or area of the change (e.g., `chromium`, `pdfengines`, `api`).
Stage specific files. Never `git add -A` or `git add .`.
### Checklist
Before opening the PR, confirm:
- [ ] No backward-compatibility regression. See [Backward compatibility](#backward-compatibility).
- [ ] Code conventions met (error wrapping, logging, telemetry, import ordering, no panics, no business logic in `cmd/`). See [Code conventions](#code-conventions).
- [ ] Documentation conventions met (Godoc on every exported identifier, `doc.go` for new packages, tone). See [Documentation conventions](#documentation-conventions).
- [ ] `make fmt && make lint && make prettify && make lint-prettier` pass with zero warnings.
- [ ] `make test-unit` passes.
- [ ] Relevant `make test-integration TAGS=...` passes.
- [ ] Bruno collection updated if routes were added or modified.
## Further reading
- [`test/integration/README.md`](test/integration/README.md) — Gherkin step reference, available tags, writing new tests.
- [`.bruno/README.md`](.bruno/README.md) — `.bru` file format, conventions, route update checklist.
- [`pkg/modules/pdfengines/README.md`](pkg/modules/pdfengines/README.md) — adding new engine features (Makefile variable and flag).