From 7a860861a34e523866897d71325c9c1b4b299ddb Mon Sep 17 00:00:00 2001 From: "Mingyu Chen (Rayner)" Date: Fri, 24 Apr 2026 13:33:58 -0700 Subject: [PATCH] chore(docs): add governance pilot fixtures to exercise lint rules Fixture PR to verify each docs governance check family end-to-end: front matter, markdown structure, sidebar orphan, link gate, SEO/GEO, SQL function doc quality, feature doc quality, and i18n/version sync. Locally triggers 31 distinct rules, including the blocking changed-only internal link gate (link-missing-target and link-missing-anchor). Fixtures live under docs/_governance-pilot/ plus one SQL function fixture under docs/sql-manual/sql-functions/... A single-line fixture edit is added to an existing zh-CN FAQ to exercise i18n-sync-source-counterpart; that line is a marked HTML comment. Not intended to merge as-is; the author will review before pushing. fix(ci): post docs AI review comment via REST to avoid GraphQL permission The first-time comment path used gh pr comment, which internally issues the GraphQL addComment mutation and requires pull-requests: write. The job only grants pull-requests: read (plus issues: write for the existing update path), so the first comment failed with "Resource not accessible by integration (addComment)". Replace gh pr comment with gh api POST against the issues/{number}/comments REST endpoint, which accepts the issues: write scope the job already grants, and mirrors the PATCH path used when a previous comment exists. fix(ci): split Docs AI Review comment into workflow_run workflow Pull requests from forks run pull_request workflows with a read-only GITHUB_TOKEN regardless of declared permissions, so the inline comment step could never post on fork PRs and returned 403 on both GraphQL and REST comment endpoints. Split the flow following the GitHub workflow_run pattern: - docs-ai-review.yml (pull_request trigger) now only prepares the packet and uploads it as an artifact, together with a pr-metadata JSON describing the PR number, head SHA, base SHA and trigger name. It no longer tries to comment. - docs-ai-review-comment.yml (workflow_run trigger on the first workflow) downloads the artifact from the completed run, parses the metadata, and upserts the advisory comment via REST. Because workflow_run runs in the base-repo context, its GITHUB_TOKEN honors the declared issues: write permission even for fork-originated PRs. The comment workflow does not check out or execute any code from the fork. It only consumes the prebuilt packet and metadata JSON, which avoids the security footgun usually associated with giving write permissions to fork-triggered runs. --- docs/_governance-pilot/feature-doc-bad.md | 13 ++++++ docs/_governance-pilot/frontmatter-missing.md | 13 ++++++ .../frontmatter-type-errors.md | 16 ++++++++ docs/_governance-pilot/i18n-sync-only-en.md | 12 ++++++ docs/_governance-pilot/links-broken.md | 24 +++++++++++ .../markdown-structure-bad.md | 32 +++++++++++++++ docs/_governance-pilot/seo-bad-a.md | 9 +++++ docs/_governance-pilot/seo-bad-b.md | 9 +++++ docs/_governance-pilot/sidebar-orphan.md | 13 ++++++ .../doris-governance-fixture-bad.md | 40 +++++++++++++++++++ .../current/faq/bi-faq.md | 2 + 11 files changed, 183 insertions(+) create mode 100644 docs/_governance-pilot/feature-doc-bad.md create mode 100644 docs/_governance-pilot/frontmatter-missing.md create mode 100644 docs/_governance-pilot/frontmatter-type-errors.md create mode 100644 docs/_governance-pilot/i18n-sync-only-en.md create mode 100644 docs/_governance-pilot/links-broken.md create mode 100644 docs/_governance-pilot/markdown-structure-bad.md create mode 100644 docs/_governance-pilot/seo-bad-a.md create mode 100644 docs/_governance-pilot/seo-bad-b.md create mode 100644 docs/_governance-pilot/sidebar-orphan.md create mode 100644 docs/sql-manual/sql-functions/scalar-functions/string-functions/doris-governance-fixture-bad.md diff --git a/docs/_governance-pilot/feature-doc-bad.md b/docs/_governance-pilot/feature-doc-bad.md new file mode 100644 index 0000000000000..24a199f16f0a7 --- /dev/null +++ b/docs/_governance-pilot/feature-doc-bad.md @@ -0,0 +1,13 @@ +--- +title: "Fixture: feature doc missing sections" +description: "This fixture is tagged as a feature doc but intentionally omits most required sections so that feature-doc-section-required fires for each one." +doc_type: feature +--- + +# Fixture: feature doc missing sections + +## Random other section + +Only an unrelated section is present. Overview, Quick Start, +Parameters/Options, Examples, Error handling and Best practices are all +missing on purpose. diff --git a/docs/_governance-pilot/frontmatter-missing.md b/docs/_governance-pilot/frontmatter-missing.md new file mode 100644 index 0000000000000..1adc7dd82a577 --- /dev/null +++ b/docs/_governance-pilot/frontmatter-missing.md @@ -0,0 +1,13 @@ +--- +language: en +--- + +# Fixture: frontmatter missing + +This page intentionally omits both `title` and `description` front matter to +trigger the frontmatter-title-required and frontmatter-description-required +rules. + +## Body + +Some text to satisfy the body requirement. diff --git a/docs/_governance-pilot/frontmatter-type-errors.md b/docs/_governance-pilot/frontmatter-type-errors.md new file mode 100644 index 0000000000000..43f5281dbb141 --- /dev/null +++ b/docs/_governance-pilot/frontmatter-type-errors.md @@ -0,0 +1,16 @@ +--- +title: "Fixture: frontmatter type errors" +description: "This fixture has frontmatter fields with the wrong types to trigger the frontmatter type rules in the docs governance lint." +slug: 12345 +keywords: 42 +tags: "should-be-array" +sidebar_position: "not-a-number" +--- + +# Fixture: frontmatter type errors + +Intentionally wrong types on `slug`, `keywords`, `tags`, `sidebar_position`. + +## Body + +Content body. diff --git a/docs/_governance-pilot/i18n-sync-only-en.md b/docs/_governance-pilot/i18n-sync-only-en.md new file mode 100644 index 0000000000000..be18b3739728a --- /dev/null +++ b/docs/_governance-pilot/i18n-sync-only-en.md @@ -0,0 +1,12 @@ +--- +title: "Fixture: i18n sync only English" +description: "This fixture intentionally ships only the English current-version copy so the i18n-sync lint reports missing zh-CN, missing 4.x, and the Japanese candidate." +--- + +# Fixture: i18n sync only English + +This doc exists only in English `current`. The i18n sync lint should report: + +- `i18n-sync-version-missing` for the 4.x counterpart +- `i18n-sync-locale-missing` for the zh-CN counterpart +- `i18n-sync-locale-candidate` for the Japanese candidate diff --git a/docs/_governance-pilot/links-broken.md b/docs/_governance-pilot/links-broken.md new file mode 100644 index 0000000000000..994e3cea704f9 --- /dev/null +++ b/docs/_governance-pilot/links-broken.md @@ -0,0 +1,24 @@ +--- +title: "Fixture: broken links" +description: "This fixture intentionally contains broken internal links and missing anchors to trigger the blocking changed-only link gate." +--- + +# Fixture: broken links + +## Missing internal file + +See [this missing doc](./does-not-exist.md) which should trigger the +internal-file-missing rule. + +## Missing anchor in existing doc + +See [missing anchor](../gettingStarted/what-is-apache-doris.md#this-anchor-does-not-exist) +which should trigger the missing-anchor rule. + +## Missing route + +Also [this route](/docs/this-route-does-not-exist) should not resolve. + +## External link (report-only today) + +See the [example external link](https://this-domain-absolutely-does-not-exist-doris-governance.invalid/some-page). diff --git a/docs/_governance-pilot/markdown-structure-bad.md b/docs/_governance-pilot/markdown-structure-bad.md new file mode 100644 index 0000000000000..6f7cfdb5d2754 --- /dev/null +++ b/docs/_governance-pilot/markdown-structure-bad.md @@ -0,0 +1,32 @@ +--- +title: "Fixture: markdown structure issues" +description: "This fixture intentionally violates Markdown structure rules to trigger code fence, heading and CJK spacing lints." +--- + +# First H1 heading + +Some intro text in English. 这里是中文和English单词直接相连，没空格，应该触发 markdown-cjk-spacing 规则。例如 Doris3.0 这种写法也会触发。 + +#### Skipped from H1 to H4 to trigger heading increment rule + +Body under an invalid heading jump. + +## + +Above heading is empty so it should trigger markdown-empty-heading. + +# Second H1 which should not exist + +This second H1 should trigger markdown-single-h1. + +## Code fence without language + +``` +SELECT * FROM tbl; +``` + +## Code fence with language (control) + +```sql +SELECT 1; +``` diff --git a/docs/_governance-pilot/seo-bad-a.md b/docs/_governance-pilot/seo-bad-a.md new file mode 100644 index 0000000000000..357a99cc1c196 --- /dev/null +++ b/docs/_governance-pilot/seo-bad-a.md @@ -0,0 +1,9 @@ +--- +title: "Fixture SEO Duplicate Title" +description: "Apache Doris documentation." +--- + +# Fixture SEO duplicate title (a) + +Intentionally a very short and generic description. This page shares its +title with `seo-bad-b.md` to trigger the duplicate-title rule. diff --git a/docs/_governance-pilot/seo-bad-b.md b/docs/_governance-pilot/seo-bad-b.md new file mode 100644 index 0000000000000..2af29e157c279 --- /dev/null +++ b/docs/_governance-pilot/seo-bad-b.md @@ -0,0 +1,9 @@ +--- +title: "Fixture SEO Duplicate Title" +description: "Docs." +--- + +# Fixture SEO duplicate title (b) + +Intentionally duplicate title + too-short generic description to exercise +seo-title-duplicate, seo-description-length and seo-description-generic. diff --git a/docs/_governance-pilot/sidebar-orphan.md b/docs/_governance-pilot/sidebar-orphan.md new file mode 100644 index 0000000000000..1be0b4a0fa8c9 --- /dev/null +++ b/docs/_governance-pilot/sidebar-orphan.md @@ -0,0 +1,13 @@ +--- +title: "Fixture: sidebar orphan" +description: "This fixture is a new doc that is intentionally not registered in sidebars.ts to trigger the sidebar orphan rule." +--- + +# Fixture: sidebar orphan + +This doc id is not added to `sidebars.ts`, so it should be reported as an +orphan by the sidebar lint. + +## Body + +Nothing linkable here. diff --git a/docs/sql-manual/sql-functions/scalar-functions/string-functions/doris-governance-fixture-bad.md b/docs/sql-manual/sql-functions/scalar-functions/string-functions/doris-governance-fixture-bad.md new file mode 100644 index 0000000000000..cb5f89be796bc --- /dev/null +++ b/docs/sql-manual/sql-functions/scalar-functions/string-functions/doris-governance-fixture-bad.md @@ -0,0 +1,40 @@ +--- +title: "doris_governance_fixture_bad" +description: "Fixture SQL function documentation with intentionally broken structure to trigger the SQL function governance lint rules." +--- + +# doris_governance_fixture_bad + +## Syntax + +```sql +doris_governance_fixture_bad(expr) +``` + +```python +# extra code block in Syntax section to violate sql-function-syntax-sql-code-block +print("bad") +``` + +## Description + +Intentionally placed after Syntax, violating sql-function-section-order. + +## Parameters + +Parameters are described as a bullet list to violate sql-function-parameters-table: + +- `expr`: some expression. + +## Return Value + +Returns something useful. + +## Example + +```sql +SELECT doris_governance_fixture_bad('x'); +``` + +No expected `text` output block is provided, so sql-function-example-output +should fire here. diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/faq/bi-faq.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/faq/bi-faq.md index 57f547101533d..e204db001eb1e 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/faq/bi-faq.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/faq/bi-faq.md @@ -6,6 +6,8 @@ } --- + + ## Power BI ### Q1. JDBC 拉取表到 Desktop Power BI 时报错 Timeout expired. The timeout period elapsed prior to completion of the operation or the server is not responding.