From a362bb2c2141779a40cff194a52776f14ffab257 Mon Sep 17 00:00:00 2001 From: Yuchao Yan Date: Tue, 13 Oct 2026 11:11:17 +0800 Subject: [PATCH] Require template-first lint documentation examples Enforce supported incorrect/correct template pairs in the queue, promotion, implementation, and validation skills. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 832854b7-de67-4f1f-8fe1-6a3e9897aeee --- .../SKILL.md | 8 ++++++++ .github/skills/lintdiff-rule-promote/SKILL.md | 15 +++++++++------ .../skills/typespec-lint-implement/SKILL.md | 19 +++++++++++++------ .../skills/typespec-lint-validate/SKILL.md | 4 ++++ 4 files changed, 34 insertions(+), 12 deletions(-) diff --git a/.github/skills/do-linter-development-task-one-by-one/SKILL.md b/.github/skills/do-linter-development-task-one-by-one/SKILL.md index bc7d3bf2d1..fc5da7dbe8 100644 --- a/.github/skills/do-linter-development-task-one-by-one/SKILL.md +++ b/.github/skills/do-linter-development-task-one-by-one/SKILL.md @@ -836,6 +836,14 @@ one session to execute both publication phases. > and ruleset enablement unless the evidence requires reporting a blocker. > Pass the same no-skill-edits/no-skill-update-PR ownership constraint. > +> Enforce the shared +> [example authoring policy](../typespec-lint-implement/SKILL.md#example-authoring) +> in promotion documentation: use supported standard templates instead of raw +> routes whenever they can demonstrate both incorrect and correct behavior. +> Require a documented template limitation for handwritten exceptions; a generic +> HTTP audience does not waive an available ARM template pair. Verify diagnostic +> evidence for the actual final snippets before publication and review handoff. +> > Follow promotion through draft PR creation or update. Record the absolute > promotion worktree and canonical promotion PR URL. A confirmed source defect > returns `source-repair-required` with the complete cycle handoff immediately; diff --git a/.github/skills/lintdiff-rule-promote/SKILL.md b/.github/skills/lintdiff-rule-promote/SKILL.md index 6374edeb1d..0a323e9ca3 100644 --- a/.github/skills/lintdiff-rule-promote/SKILL.md +++ b/.github/skills/lintdiff-rule-promote/SKILL.md @@ -576,9 +576,11 @@ library documentation following the mechanics merely to explain the migration - include realistic TypeSpec incorrect and correct examples - apply the shared [example authoring policy](../typespec-lint-implement/SKILL.md#example-authoring): - choose the example audience independently of the destination package, use - standard templates with named customizations for ARM resource scenarios, and - justify any handwritten ARM exception + use supported standard templates for the incorrect/correct pair whenever they + can preserve the diagnostic contrast, rather than raw routes; choose the + audience independently of the destination package, but do not use generic HTTP + labeling to omit a supported ARM template pair for an ARM-applicable rule; + justify handwritten exceptions with the inspected template limitation - pass the [documentation example validation](../typespec-lint-validate/SKILL.md#documentation-example-validation) gate for the actual incorrect/correct snippets; preserve the diagnostic contrast rather than substituting an exempt default template response @@ -939,9 +941,10 @@ promotion diff. The review should inspect: rationale, and any Swagger/LintDiff provenance being confined to a provenance section - example audience and template selection under the shared authoring policy, - justified handwritten ARM exceptions, and diagnostic evidence for the final - incorrect/correct snippets with the target rule enabled; compilation or a - passing exempt default-template example alone does not satisfy this gate + template-based incorrect/correct examples whenever supported, justified + handwritten exceptions, and diagnostic evidence for the final snippets with + the target rule enabled; generic HTTP labeling, compilation, or a passing + exempt default-template example alone does not satisfy this gate - generated docs and formatting drift, especially after rule renames: `packages//README.md`, `website/src/content/docs/docs/libraries//reference/linter.md`, and diff --git a/.github/skills/typespec-lint-implement/SKILL.md b/.github/skills/typespec-lint-implement/SKILL.md index f988634c4d..989322109d 100644 --- a/.github/skills/typespec-lint-implement/SKILL.md +++ b/.github/skills/typespec-lint-implement/SKILL.md @@ -103,12 +103,19 @@ audience: a shared Core rule can still need an ARM resource example. - For ARM resource scenarios, use standard ARM operation templates in both the incorrect and correct examples. Express the violation through supported named customization arguments and omit unchanged defaults. -- For data-plane or generic examples, use authoring patterns appropriate to that - audience; do not introduce ARM solely because the rule also applies to ARM. -- Before using a handwritten ARM route or operation, inspect the relevant - template's customization points. If none can express the rule-owned behavior - being explained, record that limitation and the reason for the handwritten - example in validation evidence or PR notes. Brevity alone is not a reason. +- For every audience, prefer supported standard operation templates over raw + routes or handwritten operations whenever templates can demonstrate both the + incorrect and correct behavior. Inspect the relevant template's customization + points before choosing handwritten examples. Use the template appropriate to + the audience; do not introduce ARM solely because the rule also applies to ARM. +- Choosing a generic HTTP audience does not waive template selection. If an + ARM-applicable rule can demonstrate its behavior with standard ARM templates, + include that template-based incorrect/correct pair rather than using only raw + routes. Additional audience-specific examples may supplement it. +- Use handwritten routes or operations only when no suitable supported template + can preserve the rule-owned diagnostic contrast. Record the inspected + template/customization limitation and the reason for the exception in validation + evidence or PR notes. Brevity or destination package alone is not a reason. - Preserve the semantic contrast when adopting templates. Both examples must reach the rule's intended check; the correction should fix the violation, not merely switch to an exempt construct. For an implicit-response-body rule, diff --git a/.github/skills/typespec-lint-validate/SKILL.md b/.github/skills/typespec-lint-validate/SKILL.md index d0b94526cf..5cef5b2543 100644 --- a/.github/skills/typespec-lint-validate/SKILL.md +++ b/.github/skills/typespec-lint-validate/SKILL.md @@ -117,6 +117,10 @@ do not replace the published operation or response shape with an easier test. or made the correction pass only through an exemption. For implicit response examples, preserve implicit payloads rather than switching to explicit `@body` or `@bodyRoot` bodies outside the rule's scope. +- Enforce the template-first authoring policy: when supported templates can + demonstrate the incorrect/correct pair, require those templates instead of raw + routes. A generic HTTP audience or successful compilation is not an exception; + require a documented template limitation for any handwritten fallback. - Record the example audience, chosen template/customization or justified handwritten exception, and diagnostic evidence in the validation handoff or PR notes. Reuse existing example infrastructure or a scratch workflow instead