docs: prioritize idiomatic TypeSpec over emitter parity in lintdiff migrations - #5446
Merged
Yuchao Yan (msyyc) merged 1 commit intoSep 10, 2026
Conversation
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Yuchao Yan (msyyc)
requested review from
Mark Cowlishaw (markcowl),
Timothee Guerin (timotheeguerin) and
Jeff Fisher (xirzec)
as code owners
September 10, 2026 00:53
Yuchao Yan (msyyc)
merged commit Sep 10, 2026
0d9b127
into
Azure:feature/lintdiff-migration-new
3 checks passed
Yuchao Yan (msyyc)
deleted the
docs/lintdiff-idiomatic-typespec-guidance
branch
September 10, 2026 00:55
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Update only
.github/skills/develop-lintdiff-rule/SKILL.mdto codify the migration principle settled in PR #5361: prefer idiomatic TypeSpec validation and preserve Swagger parity only where it naturally maps to TypeSpec semantics.Exact executable Swagger behavior is not the migration contract when reproducing it requires non-idiomatic checks, AutoRest schema formatting/encoding simulation, or handling constructs already invalidated by TypeSpec or Azure rules. The guidance now requires tests showing that added special cases affect valid supported TypeSpec; otherwise, omit the complexity and document the intentional parity gap.
Align coverage classification, the semantic completeness gate, fixture requirements, migration evidence, and review guidance with this priority. Corpus/lintdiff and emission-matrix evidence remain useful research tools, not mandates to reproduce emitter behavior. This follows Timothée Guérin's plain-model/indexer guidance and Catalina Peralta's confirmation of the idiomatic-TypeSpec-first principle.
Scope
Independent documentation-only PR based on and targeting
feature/lintdiff-migration-new, notmain. No production rules, fixtures, generated corpus data, dependency changes, or release metadata. Chronus excludes Markdown files from change detection.Validation
git diff --check.