From 3d9b2deb59bca8e478c5dfe48f7787fed06b972e Mon Sep 17 00:00:00 2001 From: Julien Neuhart Date: Sun, 8 Feb 2026 19:22:36 +0100 Subject: [PATCH] fix(style): AGENTS.md --- AGENTS.md | 69 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 35 insertions(+), 34 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 00087572..294530dc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,62 +4,63 @@ As an AI agent working on the Gotenberg repository, you are expected to act with ## 1. Core Philosophy & Stability -* **Backward Compatibility is Law:** This project creates a public API. Never modify existing flags, configuration environment variables, or API form fields unless explicitly instructed to perform a breaking change. If a change is breaking, it must be flagged immediately in the plan. -* **Defensive Programming:** Assume input data is malformed. Handle errors explicitly. Do not panic. -* **Atomic Commits:** Isolate refactoring from feature additions. A Pull Request should do one thing well. +- **Backward Compatibility is Law:** This project creates a public API. Never modify existing flags, configuration environment variables, or API form fields unless explicitly instructed to perform a breaking change. If a change is breaking, it must be flagged immediately in the plan. +- **Defensive Programming:** Assume input data is malformed. Handle errors explicitly. Do not panic. +- **Atomic Commits:** Isolate refactoring from feature additions. A Pull Request should do one thing well. ## 2. Development Workflow & Tooling You must rely strictly on the project's Makefile for build and verification tasks. Do not run `go` commands directly unless debugging a specific package requires it. -* **Formatting:** Run `make fmt` to format Go code before committing. -* **Linting:** - * Run `make lint` to ensure Go code strictly adheres to the `.golangci.yml` configuration. - * Run `make lint-prettier` to verify formatting for non-Go files (Markdown, YAML, etc.). - * Zero linting errors are permitted. -* **Building:** Run `make build` to verify compilation and Docker image construction. +- **Formatting:** Run `make fmt` to format Go code before committing. +- **Linting:** + - Run `make lint` to ensure Go code strictly adheres to the `.golangci.yml` configuration. + - Run `make lint-prettier` to verify formatting for non-Go files (Markdown, YAML, etc.). + - Zero linting errors are permitted. +- **Building:** Run `make build` to verify compilation and Docker image construction. ## 3. Architecture & Code Structure -* **Idiomatic Go:** Follow "Effective Go" principles. -* **Directory Separation:** - * `cmd/`: Application entry points only. Contains wiring and startup logic. **No business logic is permitted here.** - * `pkg/`: Core library code and modules. All business logic resides here. -* **Module System:** Gotenberg is modular (e.g., Chromium, LibreOffice). When adding features, determine if they belong to an existing module or require a new strict isolation. +- **Idiomatic Go:** Follow "Effective Go" principles. +- **Directory Separation:** + - `cmd/`: Application entry points only. Contains wiring and startup logic. **No business logic is permitted here.** + - `pkg/`: Core library code and modules. All business logic resides here. +- **Module System:** Gotenberg is modular (e.g., Chromium, LibreOffice). When adding features, determine if they belong to an existing module or require a new strict isolation. ## 4. Testing Standards Gotenberg utilizes a split testing strategy. **Integration tests are the primary and preferred method for verifying features.** -* **Integration Tests (`make test-integration`):** - * **First Priority:** Always start here when adding features or routes. - * Gotenberg uses **Gherkin (Godog)** for end-to-end verification. - * You **must** create or update the corresponding `.feature` file in `test/integration`. - * These tests run within the Docker context; ensure environment consistency. -* **Unit Tests (`make test-unit`):** - * Use table-driven tests for pure logic within `pkg/`. - * Mock external dependencies (filesystem, network) where appropriate. +- **Integration Tests (`make test-integration`):** + - **First Priority:** Always start here when adding features or routes. + - Gotenberg uses **Gherkin (Godog)** for end-to-end verification. + - You **must** create or update the corresponding `.feature` file in `test/integration`. + - These tests run within the Docker context; ensure environment consistency. +- **Unit Tests (`make test-unit`):** + - Use table-driven tests for pure logic within `pkg/`. + - Mock external dependencies (filesystem, network) where appropriate. ## 5. Documentation Requirements -* **No README Updates:** Do not modify the root `README.md` unless explicitly asked. -* **GoDoc is Mandatory:** - * **New Packages:** If creating a new package, you must include a `doc.go` file containing the package-level documentation. - * **Exported Symbols:** Every exported function, type, constant, and variable must have a proper GoDoc comment starting with its name. - * **Quality:** Comments must be complete sentences explaining *what* the symbol does and *how* to use it. - * **Example:** - ```go - // Convert transforms the input document to PDF using the Chromium engine. - // It returns an error if the connection to the browser instance fails. - func Convert(...) error - ``` +- **No README Updates:** Do not modify the root `README.md` unless explicitly asked. +- **GoDoc is Mandatory:** + - **New Packages:** If creating a new package, you must include a `doc.go` file containing the package-level documentation. + - **Exported Symbols:** Every exported function, type, constant, and variable must have a proper GoDoc comment starting with its name. + - **Quality:** Comments must be complete sentences explaining _what_ the symbol does and _how_ to use it. + - **Example:** + ```go + // Convert transforms the input document to PDF using the Chromium engine. + // It returns an error if the connection to the browser instance fails. + func Convert(...) error + ``` ## 6. Definition of Done A task is considered complete only when: + 1. The code compiles via `make build`. 2. The code is formatted via `make fmt`. 3. All linters pass via `make lint` and `make lint-prettier`. 4. Integration scenarios pass via `make test-integration`. 5. Unit tests pass via `make test-unit`. -6. All exported symbols and new packages have compliant GoDoc. \ No newline at end of file +6. All exported symbols and new packages have compliant GoDoc.