diff --git a/.codeant/review.json b/.codeant/review.json index cd1aa7e..20b6977 100644 --- a/.codeant/review.json +++ b/.codeant/review.json @@ -74,7 +74,7 @@ }, { "id": "website-docs-version-markers", - "description": "website/docs is the unreleased documentation; website/versioned_docs holds frozen release snapshots that must never be edited, because changing one rewrites history for users still on that version. A documented API addition must carry a version marker in one of these exact forms: _X.Y+_ appended to an API table cell, _Added in X.Y._ opening a prose paragraph, or a trailing // X.Y+ comment inside a code block. Changed behaviour takes _Changed in X.Y._ plus one line on what it was before. Every option, function and rule name in the docs must match an exported identifier or a registered rule name exactly - a wrong name is a support burden, not a typo. Internal links are checked at build time and intro.md uses slug: / so its links must be file-relative.", + "description": "website/docs is the unreleased documentation; website/versioned_docs holds frozen release snapshots that must never be edited, because changing one rewrites history for users still on that version. A documented API addition must carry a version marker in one of these exact forms: _X.Y+_ appended to an API table cell, _Added in X.Y._ opening a prose paragraph, or a trailing // X.Y+ comment inside a code block. Changed behaviour takes _Changed in X.Y._ plus one line on what it was before. Every name the docs present as sqlguard's own - an option, function, type or rule - must match an exported identifier or a registered rule name exactly; a wrong name is a support burden, not a typo. This applies to sqlguard's API only. Identifiers owned by the standard library, a driver, an ORM or a database (sql.Open, stdlib.GetConnector, gorm.Plugin, interpolateParams, standard_conforming_strings, ...) are correct when they match upstream, and naming one is not a violation. Internal links are checked at build time and intro.md uses slug: / so its links must be file-relative.", "files": ["website/docs/**/*.md", "website/docs/**/*.mdx", "README.md", "CHANGELOG.md"], "scope": ["pr", "ide"] }, diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 3c1f51c..284c501 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -213,9 +213,14 @@ reviews: - path: "website/docs/**" instructions: >- Docusaurus source for the unreleased docs. Verify every Go snippet - compiles against the current API and that option, function and rule - names match the exported identifiers / registered rule names exactly — - a wrong name here is a support burden, not a typo. This site is + compiles against the current API and that every name presented as + sqlguard's own — option, function, type or rule — matches an exported + identifier / registered rule name exactly; a wrong name here is a + support burden, not a typo. That applies to sqlguard's API only: + identifiers owned by the standard library, a driver, an ORM or a + database (sql.Open, stdlib.GetConnector, gorm.Plugin, + interpolateParams, standard_conforming_strings, …) are correct when + they match upstream, and naming one is not a violation. This site is versioned by snapshot, not per release: additive changes are marked inline instead of being snapshotted, so check that anything documenting a new API carries its version marker — `_0.3+_` appended to an API diff --git a/.greptile/config.json b/.greptile/config.json index 6d0f26c..9731818 100644 --- a/.greptile/config.json +++ b/.greptile/config.json @@ -74,7 +74,7 @@ }, { "id": "website-docs-version-markers", - "rule": "A documented API addition on this page must carry a version marker in one of these exact forms: '_X.Y+_' appended to a table cell's description, '_Added in X.Y._' opening a prose paragraph, or a trailing '// X.Y+' comment inside a code block. Documented behaviour that changed must use '_Changed in X.Y._' followed by one line describing the prior behaviour. Every option, function and rule name must match an exported identifier or registered rule name exactly — flag a name that does not exist in the Go source. See website/VERSIONING.md rules 1 and 2. Never suggest an edit to website/versioned_docs/ — those are frozen release snapshots.", + "rule": "A documented API addition on this page must carry a version marker in one of these exact forms: '_X.Y+_' appended to a table cell's description, '_Added in X.Y._' opening a prose paragraph, or a trailing '// X.Y+' comment inside a code block. Documented behaviour that changed must use '_Changed in X.Y._' followed by one line describing the prior behaviour. Every name the docs present as sqlguard's own — an option, function, type or rule — must match an exported identifier or registered rule name exactly; flag a sqlguard name that does not exist in the Go source. This covers sqlguard's API only: identifiers owned by the standard library, a driver, an ORM or a database (sql.Open, stdlib.GetConnector, gorm.Plugin, interpolateParams, standard_conforming_strings, …) are correct when they match upstream, and naming one is not a violation. See website/VERSIONING.md rules 1 and 2. Never suggest an edit to website/versioned_docs/ — those are frozen release snapshots.", "scope": ["website/docs/**/*.md"], "severity": "medium" }, diff --git a/AGENTS.md b/AGENTS.md index 8cfe16a..cad7077 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -97,9 +97,12 @@ version does (served at `/docs/`). Versions are `MAJOR.MINOR`. API table cell, open a paragraph with `_Added in 0.3._`, add a trailing `// 0.3+` comment in a code block, or write `_Changed in 0.3._` plus one line on the previous behaviour. -- **Names must be exact.** Every option, function and rule name in the docs - must match an exported identifier or registered rule name; check the source - before writing one. +- **Names must be exact.** Every name the docs present as sqlguard's own — an + option, function, type or rule — must match an exported identifier or + registered rule name; check the source before writing one. This is about + sqlguard's API: a third-party identifier the docs name (`sql.Open`, + `stdlib.GetConnector`, `gorm.Plugin`, `interpolateParams`, + `standard_conforming_strings`) is correct when it matches upstream. - **Blog** is wired up but has no posts, so the navbar/footer carry no Blog link; add the links in `docusaurus.config.ts` together with the first post.