Skip to content

Clarify v1 versioning direction - #1227

Merged
Gudge (MGudgin) merged 1 commit into
mainfrom
user/gudge/v1-versioning-docs
Sep 24, 2026
Merged

Gudge (MGudgin) merged 1 commit into
mainfrom
user/gudge/v1-versioning-docs

Conversation

@MGudgin

@MGudgin Gudge (MGudgin) commented Sep 22, 2026 •

Copy link
Copy Markdown
Member

This PR updates the versioning design to distinguish the current v0.x exact-version SDK behavior from the planned v1 major-line model.

Details:

  • Define source-compatible minor evolution within an SDK major line.
  • Record that v1.0 starts from v0.9 and v0.10-only surfaces move to v1.1 development.
  • Document registry-owned artifact-generation and request-root metadata.
  • Align deprecation aliases with exact contracts and major-version compatibility.
  • Clarify that development-only structures do not imply an experimental JSON wrapper.

Tests

  • git -c core.whitespace=cr-at-eol diff --check
  • Documentation-only change; no build or test suites were required.
Microsoft Reviewers: Open in CodeFlow

@MGudgin
Gudge (MGudgin) requested a review from a team as a code owner September 22, 2026 15:38
Copilot AI balanced review requested due to automatic review settings September 22, 2026 15:38
@azure-pipelines

Copy link
Copy Markdown
Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

The alias policy incorrectly claims schema/parser agreement for legacy v0.6-v0.8 contracts.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 Low severity

Open (1)
What changed in this PR

Clarifies the transition from exact v0.x contracts to planned major-line v1 SDK versioning.

Changes:

  • Defines v1 minor-version compatibility.
  • Documents v1.0/v1.1 contract lineage and registry metadata.
  • Revises deprecation-alias policy.
File Description
docs/​versioning.md Updates versioning, artifact-generation, and alias guidance.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread docs/versioning.md Resolved
Copilot AI review requested due to automatic review settings September 22, 2026 15:57
@MGudgin
Gudge (MGudgin) force-pushed the user/gudge/v1-versioning-docs branch from cf93119 to bb3f93d Compare September 22, 2026 15:57

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟢 Approval recommended

The documentation accurately reflects the current exact-contract architecture and planned v1 direction.

Review effort: Balanced
Findings: None

Resolved since last review (1)

Comment thread docs/versioning.md Resolved
Comment thread docs/versioning.md Resolved
Comment thread docs/versioning.md Resolved
Comment thread docs/versioning.md Resolved
Comment thread docs/versioning.md Resolved
Comment thread docs/versioning.md Resolved

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🕐

@microsoft-github-policy-service microsoft-github-policy-service Bot added the Needs-Author-Feedback Waiting for additional information or action from the issue or pull-request author. label Sep 22, 2026
This PR updates the versioning design to distinguish current v0.x exact
contract selection from the planned v1 SDK major-line model.

Details

* Define source-compatible minor evolution within an SDK major line.
* Record the v1.0 baseline and v1.1 development-contract transition.
* Document registry-owned artifact and request-root metadata.
* Align deprecation aliases with exact contracts and major compatibility.
* Document legacy stable-schema exceptions for parser aliases.

Tests

* `git -c core.whitespace=cr-at-eol diff --check`

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 3e39bcce-697d-4dfe-918d-547fb944be79
Generated-with: gpt-5.6-sol
Copilot AI review requested due to automatic review settings September 22, 2026 19:04
@MGudgin
Gudge (MGudgin) force-pushed the user/gudge/v1-versioning-docs branch from bb3f93d to bce9014 Compare September 22, 2026 19:04
@microsoft-github-policy-service microsoft-github-policy-service Bot added Needs-Attention Requires attention or a decision from the MXC maintainers. and removed Needs-Author-Feedback Waiting for additional information or action from the issue or pull-request author. labels Sep 22, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

The documentation incorrectly states that request-root metadata drives artifact generation rather than post-generation validation.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 Low severity

Open (1)

Comment thread docs/versioning.md
Comment on lines +285 to +290
Each `ContractDescriptor` also owns whether that contract generates artifacts
and the request roots used for generation and fixture validation. Each
registered root names its fixture directory and schema definition. The codegen
gate consumes this metadata directly, so a generated contract cannot silently
omit a request root. Legacy v0.6-v0.8 contracts intentionally advertise no
generated request roots.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

:shipit:

@MGudgin
Gudge (MGudgin) merged commit 456515c into main Sep 24, 2026
29 checks passed
@MGudgin
Gudge (MGudgin) deleted the user/gudge/v1-versioning-docs branch September 24, 2026 17:22
@microsoft-github-policy-service microsoft-github-policy-service Bot removed the Needs-Attention Requires attention or a decision from the MXC maintainers. label Sep 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants