From 53c2f97008e926a68bf96d72ec5dbe9ef0602021 Mon Sep 17 00:00:00 2001 From: Julien Neuhart Date: Tue, 31 Mar 2026 12:44:13 +0200 Subject: [PATCH] docs(markdown): human-centric instead of agents first [skip ci] --- .bruno/{AGENTS.md => README.md} | 2 +- AGENTS.md | 182 +----------------- CLAUDE.md | 4 +- CONTRIBUTING.md | 162 ++++++++++++++-- GEMINI.md | 4 +- SECURITY.md | 34 ++-- .../pdfengines/{AGENTS.md => README.md} | 0 test/integration/{AGENTS.md => README.md} | 10 +- 8 files changed, 166 insertions(+), 232 deletions(-) rename .bruno/{AGENTS.md => README.md} (95%) mode change 100644 => 120000 AGENTS.md mode change 100644 => 120000 CLAUDE.md mode change 100644 => 120000 GEMINI.md rename pkg/modules/pdfengines/{AGENTS.md => README.md} (100%) rename test/integration/{AGENTS.md => README.md} (90%) diff --git a/.bruno/AGENTS.md b/.bruno/README.md similarity index 95% rename from .bruno/AGENTS.md rename to .bruno/README.md index 936c6ef4..6d4cb1d2 100644 --- a/.bruno/AGENTS.md +++ b/.bruno/README.md @@ -59,7 +59,7 @@ headers { ## Checklist When Adding/Updating a Route 1. Create or update the `.bru` file in the matching folder under `.bruno/`. -2. Include all form fields from the route handler — check `FormData*` calls in the route function. +2. Include all form fields from the route handler. Check `FormData*` calls in the route function. 3. For file upload fields (`files`, `watermark`, `stamp`, `embeds`), use `@file(...)` with a suitable test file. 4. Verify the URL path matches the route's `Path` field exactly. 5. If you add a new module folder, keep the naming consistent (e.g., `PDF Engines/Rotate/`). diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 3f189a21..00000000 --- a/AGENTS.md +++ /dev/null @@ -1,181 +0,0 @@ -# Operational Guidelines for Gotenberg - -You are working on **Gotenberg**, a Docker-based API for converting documents to PDF. It is a widely used production dependency. Stability and backward compatibility are paramount. When in doubt about whether a change is breaking, flag it rather than assuming it's safe. - -## Mandatory Workflow - -Every task MUST follow these five steps in order. Do not skip any step. - -### Step 1 — Plan - -Before writing any code, produce a plan that covers: - -- **Problem statement**: What needs to change and why. -- **Proposed solution**: The recommended approach with enough detail to implement (files to modify, interface changes, pipeline positioning, form fields, etc.). -- **Alternatives considered**: At least one alternative approach when pertinent, with a brief explanation of why the proposed solution is preferred. -- **Scope**: List every file that will be created or modified. -- **Testing strategy**: Which integration test tags will be affected, what new scenarios are needed, and whether unit tests are required. - -Present the plan to the user and wait for approval before proceeding to Step 2. If the user provides a plan, validate it against the codebase and flag any issues before implementing. - -### Step 2 — Implement - -Implement the approved plan following the coding standards and patterns described in this document. After implementation, verify the build compiles (`go build ./...`). - -### Step 3 — Test - -Write or update tests based on the plan's testing strategy: - -- **Integration tests** (primary): Gherkin scenarios in `test/integration/features/`. See [`test/integration/AGENTS.md`](test/integration/AGENTS.md) for the full reference. -- **Unit tests** (when applicable): Table-driven tests in `*_test.go` files using mocks from `pkg/gotenberg/mocks.go`. - -### Step 4 — Review - -Self-review the implementation against the [Review Checklist](#review-checklist). Fix any issues found before presenting the result to the user. - -### Step 5 — Commit - -Present the review to the user and **wait for explicit approval**. Do NOT commit until the user confirms. Once approved, create a commit following the [Conventional Commits](https://www.conventionalcommits.org/) specification: - -``` -(): -``` - -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`). - -Stage only the files related to the change. Do not use `git add -A` or `git add .`. - ---- - -## Core Principles - -- **Backward compatibility is law.** Never modify existing CLI flags, environment variables, or API form fields unless explicitly instructed to perform a breaking change. Flag any breaking change immediately. -- **Defensive programming.** Assume input is malformed. Handle errors explicitly. Never panic. -- **Atomic commits.** One feature or fix per PR. Isolate refactoring from feature work. -- **Idiomatic Go.** Follow "Effective Go" principles. All exported symbols must have GoDoc comments starting with their name. - -## Project Layout - -``` -cmd/gotenberg/ → Entry point only (wiring/startup). No business logic. -pkg/gotenberg/ → Core module system, interfaces, utilities, mocks. -pkg/modules/ → Feature modules (api, chromium, libreoffice, pdfengines, etc.). -pkg/standard/ → Wires all standard modules together via imports. -test/integration/ → Gherkin feature files + Go test infrastructure. -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. When adding features, determine if they belong in an existing module or require a new one. - -## Codebase Navigation - -- Start with `pkg/gotenberg/` for core interfaces and `pkg/modules/` for feature implementations. -- The integration test infrastructure in `test/integration/scenario/` is well-structured — read `scenario.go` and `containers.go` to understand the Gherkin step definitions before writing new tests. -- Mocks for all major interfaces are in `pkg/gotenberg/mocks.go` — use them for unit tests rather than creating new ones. -- Import ordering is enforced: standard library, third-party, then `github.com/gotenberg/gotenberg/v8` — separated by blank lines. -- When making changes, run only the relevant integration test tag rather than the full suite (40min timeout). -- Telemetry infrastructure lives in `pkg/gotenberg/telemetry.go` (global Logger, Tracer, Meter) and `pkg/gotenberg/internal/` (log handlers, OTEL SDK init). HTTP semantic conventions are in `pkg/gotenberg/semconv/`. - ---- - -## Makefile — the Only Build Interface - -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 Docker image | Before integration tests, or to verify compilation | -| `make run` | Run Gotenberg container via `docker compose` | Manual testing. Flags are 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 fmt` | Format Go code (`go fix`, `golangci-lint fmt`, `go mod tidy`) | Before every commit | -| `make lint` | Lint Go code (strict `.golangci.yml` config) | Before every commit. Zero errors permitted | -| `make lint-prettier` | Lint non-Go files (Markdown, YAML, etc.) with Prettier | Before every commit | -| `make prettify` | Format non-Go files (Markdown, YAML, etc.) with Prettier | Before every commit | -| `make test-unit` | Run unit tests (`go test -race ./...`) | After code changes to `pkg/` | -| `make test-integration` | Run integration tests (Gherkin/Godog, 40min timeout) | After any feature or route change | -| `make godoc` | Serve GoDoc at `localhost:6060` | To verify documentation | - -## Module System - -Gotenberg uses a self-registering module architecture inspired by CaddyServer. Each module: - -- Lives in `pkg/modules//` -- Implements the `gotenberg.Module` interface (at minimum `Descriptor()`) -- May also implement `gotenberg.Provisioner`, `gotenberg.Validator`, or `gotenberg.Debuggable` -- Self-registers via `init()` and is wired through `pkg/standard/` - -When adding a feature, first determine if it belongs in an existing module. Only create a new module if the feature represents a genuinely separate concern. - -## Coding Patterns - -- **Error handling:** Always wrap errors with context using `fmt.Errorf("description: %w", err)`. Never swallow errors silently. -- **Import ordering:** 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. -- **Logging:** Use `gotenberg.Logger(mod)` to get the module's slog logger during `Provision()`. All log calls must be context-aware: `logger.DebugContext(ctx, msg)`, `logger.InfoContext(ctx, msg)`, `logger.ErrorContext(ctx, msg)`. This propagates trace/span IDs into structured logs when OpenTelemetry is active. -- **Telemetry:** 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 respectively. -- **No business logic in `cmd/`:** The `cmd/gotenberg/` package is strictly for wiring and startup. - ---- - -## Review Checklist - -### Backward Compatibility - -- [ ] 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()` - -If any of these are violated, the change **must** be flagged as a breaking change. - -### Linting Standards - -The `.golangci.yml` enforces strict rules including: `gosec`, `govet`, `errcheck`, `staticcheck`, `dupl`, `bodyclose`, `exhaustive`, `errname`, `sloglint`, `gocritic`, and more. Zero linting errors are permitted. - -Formatters enforce `gci`, `gofmt`, `gofumpt`, `goimports` with import ordering: - -1. Standard library -2. Third-party packages -3. `github.com/gotenberg/gotenberg/v8` - -Three groups separated by blank lines. - -### Code Quality - -- Errors are wrapped with context: `fmt.Errorf("description: %w", err)`. No swallowed errors. -- No business logic in `cmd/`. -- No panics in production code paths. -- Input is validated defensively. -- New features belong in the correct module (or justify a new one). - -### Documentation - -- Every exported function, type, constant, and variable has a GoDoc comment starting with its name. -- New packages include a `doc.go` file. -- `README.md` is not modified unless explicitly requested. - -### Definition of Done - -A change is ready to merge only when: - -1. Code compiles: `go build ./...` -2. Code is formatted: `make fmt` -3. All linters pass: `make lint` and `make lint-prettier` -4. Integration tests pass: `make test-integration` (at minimum, the relevant `TAGS`) -5. Unit tests pass: `make test-unit` -6. All exported symbols and new packages have compliant GoDoc -7. Bruno collection is updated (if routes were added or modified) - ---- - -## Scoped Guidelines - -Detailed guidelines for specific areas of the codebase live in their own `AGENTS.md` files: - -- [`test/integration/AGENTS.md`](test/integration/AGENTS.md) — Integration test framework, Gherkin step reference, available tags, and how to write new tests. -- [`.bruno/AGENTS.md`](.bruno/AGENTS.md) — Bruno API collection structure, `.bru` file format, conventions, and route update checklist. -- [`pkg/modules/pdfengines/AGENTS.md`](pkg/modules/pdfengines/AGENTS.md) — How to add new PDF engine features (Makefile variable and flag). diff --git a/AGENTS.md b/AGENTS.md new file mode 120000 index 00000000..eada936c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1 @@ +CONTRIBUTING.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 23d03fa6..00000000 --- a/CLAUDE.md +++ /dev/null @@ -1,3 +0,0 @@ -# Claude Code — Gotenberg - -Read [AGENTS.md](AGENTS.md) first. It contains everything: core principles, project layout, coding standards, the mandatory 4-step workflow (Plan → Implement → Test → Review), integration test reference, review checklist, and Bruno collection guidelines. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 00000000..eada936c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +CONTRIBUTING.md \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 01835ef5..5833efec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to Gotenberg -Thank you for your interest in contributing to Gotenberg! This guide will help you get started. +**Gotenberg** is a Docker-based API for converting documents to PDF. It is a widely used production dependency. Stability and backward compatibility are paramount. When in doubt about whether a change is breaking, flag it rather than assuming it's safe. ## Getting Started @@ -8,7 +8,7 @@ Thank you for your interest in contributing to Gotenberg! This guide will help y - Go (see version in `go.mod`) - Docker -- Node.js (see version in `.node-version`) — for Prettier linting +- Node.js (see version in `.node-version`), for Prettier linting - [golangci-lint](https://golangci-lint.run/) v2+ ### Build and Run @@ -43,7 +43,13 @@ make test-integration TAGS="merge,split" ## Submitting a Pull Request -Before opening a PR, verify: +For non-trivial changes, outline your approach before writing code. Open an issue or draft PR describing: + +- What needs to change and why. +- The proposed solution, with enough detail to implement (files to modify, interface changes, form fields, etc.). +- Which integration test tags will be affected and what new scenarios are needed. + +Before opening (or marking ready) a PR, verify: 1. Code compiles: `make build` 2. Code is formatted: `make fmt` and `make prettify` @@ -51,24 +57,148 @@ Before opening a PR, verify: 4. Integration tests pass: `make test-integration` (at minimum, the relevant tags) 5. Unit tests pass: `make test-unit` 6. All exported symbols and new packages have GoDoc comments +7. Bruno collection is updated (if routes were added or modified) + +Review your changes against the [Review Checklist](#review-checklist) before submitting. ### Guidelines -- **Conventional Commits.** Commit messages must follow the [Conventional Commits](https://www.conventionalcommits.org/) 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/`. +- **Integration tests first.** When adding a feature or route, start by writing the Gherkin scenario in `test/integration/features/`. See [`test/integration/README.md`](test/integration/README.md) for the full reference. +- **Unit tests** when applicable: table-driven tests in `*_test.go` files using mocks from `pkg/gotenberg/mocks.go`. -## Detailed Guidelines +### Commit Conventions -The [`AGENTS.md`](AGENTS.md) files contain comprehensive guidelines used by both human contributors and AI-assisted tools: +If committing, follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: -| File | What it covers | -| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -| [`AGENTS.md`](AGENTS.md) | Core principles, mandatory workflow, project layout, coding patterns, module system, Makefile reference, review checklist | -| [`test/integration/AGENTS.md`](test/integration/AGENTS.md) | Integration test framework (Godog/Gherkin), available tags, step reference, how to write new tests | -| [`.bruno/AGENTS.md`](.bruno/AGENTS.md) | Bruno API collection structure, `.bru` file format, conventions, route update checklist | -| [`pkg/modules/pdfengines/AGENTS.md`](pkg/modules/pdfengines/AGENTS.md) | How to add new PDF engine features (Makefile variable and flag) | +``` +(): +``` + +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`). + +Stage only the files related to the change. Do not use `git add -A` or `git add .`. + +--- + +## Core Principles + +- **Backward compatibility is law.** Never modify existing CLI flags, environment variables, or API form fields unless explicitly instructed to perform a breaking change. Flag any breaking change immediately. +- **Defensive programming.** Assume input is malformed. Handle errors explicitly. Never panic. +- **Atomic commits.** One feature or fix per PR. Isolate refactoring from feature work. +- **Idiomatic Go.** Follow "Effective Go" principles. All exported symbols must have GoDoc comments starting with their name. + +## Project Layout + +``` +cmd/gotenberg/ → Entry point only (wiring/startup). No business logic. +pkg/gotenberg/ → Core module system, interfaces, utilities, mocks. +pkg/modules/ → Feature modules (api, chromium, libreoffice, pdfengines, etc.). +pkg/standard/ → Wires all standard modules together via imports. +test/integration/ → Gherkin feature files + Go test infrastructure. +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. When adding features, determine if they belong in an existing module or require a new one. + +## Codebase Navigation + +- Start with `pkg/gotenberg/` for core interfaces and `pkg/modules/` for feature implementations. +- The integration test infrastructure in `test/integration/scenario/` is well-structured. Read `scenario.go` and `containers.go` to understand the Gherkin step definitions before writing new tests. +- Mocks for all major interfaces are in `pkg/gotenberg/mocks.go`. Use them for unit tests rather than creating new ones. +- Import ordering is enforced: standard library, third-party, then `github.com/gotenberg/gotenberg/v8`, separated by blank lines. +- When making changes, run only the relevant integration test tag rather than the full suite (40min timeout). +- Telemetry infrastructure lives in `pkg/gotenberg/telemetry.go` (global Logger, Tracer, Meter) and `pkg/gotenberg/internal/` (log handlers, OTEL SDK init). HTTP semantic conventions are in `pkg/gotenberg/semconv/`. + +--- + +## Makefile: the Only Build Interface + +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 Docker image | Before integration tests, or to verify compilation | +| `make run` | Run Gotenberg container via `docker compose` | Manual testing. Flags are 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 fmt` | Format Go code (`go fix`, `golangci-lint fmt`, `go mod tidy`) | Before every commit | +| `make lint` | Lint Go code (strict `.golangci.yml` config) | Before every commit. Zero errors permitted | +| `make lint-prettier` | Lint non-Go files (Markdown, YAML, etc.) with Prettier | Before every commit | +| `make prettify` | Format non-Go files (Markdown, YAML, etc.) with Prettier | Before every commit | +| `make test-unit` | Run unit tests (`go test -race ./...`) | After code changes to `pkg/` | +| `make test-integration` | Run integration tests (Gherkin/Godog, 40min timeout) | After any feature or route change | +| `make godoc` | Serve GoDoc at `localhost:6060` | To verify documentation | + +## Module System + +Gotenberg uses a self-registering module architecture inspired by CaddyServer. Each module: + +- Lives in `pkg/modules//` +- Implements the `gotenberg.Module` interface (at minimum `Descriptor()`) +- May also implement `gotenberg.Provisioner`, `gotenberg.Validator`, or `gotenberg.Debuggable` +- Self-registers via `init()` and is wired through `pkg/standard/` + +When adding a feature, first determine if it belongs in an existing module. Only create a new module if the feature represents a genuinely separate concern. + +## Coding Patterns + +- **Error handling:** Always wrap errors with context using `fmt.Errorf("description: %w", err)`. Never swallow errors silently. +- **Import ordering:** 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. +- **Logging:** Use `gotenberg.Logger(mod)` to get the module's slog logger during `Provision()`. All log calls must be context-aware: `logger.DebugContext(ctx, msg)`, `logger.InfoContext(ctx, msg)`, `logger.ErrorContext(ctx, msg)`. This propagates trace/span IDs into structured logs when OpenTelemetry is active. +- **Telemetry:** 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 respectively. +- **No business logic in `cmd/`:** The `cmd/gotenberg/` package is strictly for wiring and startup. + +--- + +## Review Checklist + +### Backward Compatibility + +- [ ] 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()` + +If any of these are violated, the change **must** be flagged as a breaking change. + +### Linting Standards + +The `.golangci.yml` enforces strict rules including: `gosec`, `govet`, `errcheck`, `staticcheck`, `dupl`, `bodyclose`, `exhaustive`, `errname`, `sloglint`, `gocritic`, and more. Zero linting errors are permitted. + +Formatters enforce `gci`, `gofmt`, `gofumpt`, `goimports` with import ordering: + +1. Standard library +2. Third-party packages +3. `github.com/gotenberg/gotenberg/v8` + +Three groups separated by blank lines. + +### Code Quality + +- Errors are wrapped with context: `fmt.Errorf("description: %w", err)`. No swallowed errors. +- No business logic in `cmd/`. +- No panics in production code paths. +- Input is validated defensively. +- New features belong in the correct module (or justify a new one). + +### Documentation + +- Every exported function, type, constant, and variable has a GoDoc comment starting with its name. +- New packages include a `doc.go` file. +- `README.md` is not modified unless explicitly requested. + +--- + +## Scoped Guidelines + +Detailed guidelines for specific areas of the codebase: + +- [`test/integration/README.md`](test/integration/README.md): Integration test framework, Gherkin step reference, available tags, and how to write new tests. +- [`.bruno/README.md`](.bruno/README.md): Bruno API collection structure, `.bru` file format, conventions, and route update checklist. +- [`pkg/modules/pdfengines/README.md`](pkg/modules/pdfengines/README.md): How to add new PDF engine features (Makefile variable and flag). diff --git a/GEMINI.md b/GEMINI.md deleted file mode 100644 index 58b9277d..00000000 --- a/GEMINI.md +++ /dev/null @@ -1,3 +0,0 @@ -# Gemini — Gotenberg - -Read [AGENTS.md](AGENTS.md) first. It contains everything: core principles, project layout, coding standards, the mandatory 4-step workflow (Plan → Implement → Test → Review), integration test reference, review checklist, and Bruno collection guidelines. diff --git a/GEMINI.md b/GEMINI.md new file mode 120000 index 00000000..eada936c --- /dev/null +++ b/GEMINI.md @@ -0,0 +1 @@ +CONTRIBUTING.md \ No newline at end of file diff --git a/SECURITY.md b/SECURITY.md index f281db27..c76a0170 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,40 +2,28 @@ ## Supported Versions -Please ensure to keep your environment up to date and use only the latest version of Gotenberg. -Security updates and patches will be applied only to the most recent version. +Only the latest version of Gotenberg receives security updates and patches. Keep your environment up to date. ## Reporting a Vulnerability -Your help in identifying vulnerabilities in our project is much appreciated. -We take all reports regarding security seriously. +If you discover a security vulnerability, do not publish it publicly. Send details via email to _neuhart [dot] julien [at] gmail [dot] com_ with the subject indicating a Gotenberg security vulnerability report. -If you discover a security vulnerability, please refrain from publishing it publicly. -Instead, kindly send us the details via email to _neuhart [dot] julien [at] gmail [dot] com_. - -In the subject of your email, please indicate that it's a security vulnerability report for Gotenberg. -In your message, please include: +Include: - A detailed description of the vulnerability. -- The steps to reproduce the issue. -- Any potential impact of the vulnerability on the users or system. +- Steps to reproduce the issue. +- Any potential impact on users or the system. -Please remember that this process is done in a _'best-effort'_ manner. -This means we strive to respond and act as quickly as possible, but the speed may vary depending on the severity of -the issue and our resources. - -Thank you in advance for helping to keep our project safe! +This process is handled on a _'best-effort'_ basis. Response speed may vary depending on severity and available resources. ## Disclosure Policy -Once we have received your vulnerability report, we will work to validate and reproduce the issue. -If we can confirm the vulnerability, we will proceed to: +Once a vulnerability report is received and confirmed: -- Work on a fix and a release timeline. -- Notify you when the fix has been implemented and released. -- Credit you for discovering the vulnerability (unless you request anonymity). -- Please note that we will do our best to keep you informed about the progress towards resolving the issue. +- A fix and release timeline will be prepared. +- You will be notified when the fix is released. +- You will be credited for the discovery (unless you request anonymity). ## Comments on this Policy -If you have suggestions on how this process could be improved, please submit a pull request. +If you have suggestions on how this process could be improved, submit a pull request. diff --git a/pkg/modules/pdfengines/AGENTS.md b/pkg/modules/pdfengines/README.md similarity index 100% rename from pkg/modules/pdfengines/AGENTS.md rename to pkg/modules/pdfengines/README.md diff --git a/test/integration/AGENTS.md b/test/integration/README.md similarity index 90% rename from test/integration/AGENTS.md rename to test/integration/README.md index 99df7ac5..50ac0e62 100644 --- a/test/integration/AGENTS.md +++ b/test/integration/README.md @@ -1,8 +1,8 @@ # Integration Tests - **Framework:** Gherkin (BDD) via [Godog](https://github.com/cucumber/godog), with `testcontainers-go` for Docker orchestration. -- **Feature files:** `test/integration/features/*.feature` — one file per endpoint or capability. -- **Test infrastructure:** `test/integration/scenario/` — Go step definitions, container management, HTTP helpers, PDF validation. +- **Feature files:** `test/integration/features/*.feature`, one file per endpoint or capability. +- **Test infrastructure:** `test/integration/scenario/`, Go step definitions, container management, HTTP helpers, PDF validation. - **Entry point:** `test/integration/main_test.go` (build tag: `integration`). - **Test data:** `test/integration/testdata/` @@ -51,7 +51,7 @@ make test-integration PLATFORM=linux/arm64 # Force a specific platform - `I make a "(GET|HEAD)" request to Gotenberg at the "" endpoint` - `I make a "(GET|HEAD)" request to Gotenberg at the "" endpoint with the following header(s):` (table: name | value) -- `I make a "(POST)" request to Gotenberg at the "" endpoint with the following form data and header(s):` (table: name | value | kind — where kind is `file`, `field`, or `header`) +- `I make a "(POST)" request to Gotenberg at the "" endpoint with the following form data and header(s):` (table: name | value | kind, where kind is `file`, `field`, or `header`) - `I make concurrent "(POST)" requests to Gotenberg at the "" endpoint with the following form data and header(s):` (same table format) - `I wait for the asynchronous request to the webhook` @@ -62,8 +62,8 @@ make test-integration PLATFORM=linux/arm64 # Force a specific platform - `the (response|webhook request) cookie "" should be ""` - `the (response|webhook request) body should match string:` (docstring) - `the (response|webhook request) body should contain string:` (docstring) -- `the (response|webhook request) body should match JSON:` (docstring — use `"ignore"` for dynamic values like timestamps) -- `the webhook event should match JSON:` (docstring — use `"ignore"` for dynamic values; polls for up to 5s) +- `the (response|webhook request) body should match JSON:` (docstring, use `"ignore"` for dynamic values like timestamps) +- `the webhook event should match JSON:` (docstring, use `"ignore"` for dynamic values; polls for up to 5s) - `there should be PDF(s) in the (response|webhook request)` - `there should be the following file(s) in the (response|webhook request):` (table of filenames) - `the "" PDF should have page(s)`