From d4deed562c0e6a343f33e3743a75b8413c8ba347 Mon Sep 17 00:00:00 2001 From: Claus Ibsen Date: Mon, 31 Aug 2026 10:32:17 +0200 Subject: [PATCH] chore: document adoc anchor and generated-catalog-sync guidance in AGENTS.md Prompted by a broken structured_error_exchange_properties anchor that diverged from AsciiDoc's auto-generated heading id, plus a follow-up where regenerating the source doc missed the mirrored copy under catalog/camel-catalog/src/generated/resources, breaking CI's uncommitted-changes check. Co-Authored-By: Claude Sonnet 5 Signed-off-by: Claus Ibsen --- AGENTS.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index aa8f7d3e73a2c..75bdfdca38f2a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -353,6 +353,17 @@ When writing or modifying `.adoc` documentation: version-aware reference. - **When reviewing doc PRs**, check that all `xref:` links and anchors resolve correctly, especially cross-component references that may span versions. +- **Avoid explicit `[[anchor]]` blocks before a heading.** AsciiDoc already auto-generates an id from + the heading text (prefixed with `_`, e.g. `=== Structured error exchange properties` becomes + `#_structured_error_exchange_properties`). An explicit `[[structured_error_exchange_properties]]` + anchor sets the id *without* that prefix, so it silently diverges from the id every other `xref:` + in the codebase expects and breaks the website link checker. Only add an explicit anchor when a + stable id is needed that must survive a heading rename — never as a matter of habit. +- **Component doc changes require regenerating the catalog.** Editing a component's + `src/main/docs/*.adoc` also requires regenerating and committing the mirrored copy under + `catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/`. CI's + "uncommitted changes" check fails otherwise — this applies even to small doc-only edits like + removing an anchor, not just code-driven metadata changes. ## Security Model