This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new 1d3dbc1a7348 chore: document adoc anchor and generated-catalog-sync
guidance in AGENTS.md (#25943)
1d3dbc1a7348 is described below
commit 1d3dbc1a7348046c4526a3fc81a3a946946d324b
Author: Claus Ibsen <[email protected]>
AuthorDate: Mon Aug 31 10:37:55 2026 +0200
chore: document adoc anchor and generated-catalog-sync guidance in
AGENTS.md (#25943)
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.
Signed-off-by: Claus Ibsen <[email protected]>
Co-authored-by: Claude Sonnet 5 <[email protected]>
---
AGENTS.md | 11 +++++++++++
1 file changed, 11 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
index aa8f7d3e73a2..75bdfdca38f2 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
