docs: add Component Versioning Across Channels guideline #6453
Open
docs: add Component Versioning Across Channels guideline
#6453
Conversation
Adds an interim contributor guideline at docs/Coding-Guidelines/ComponentVersioning.md establishing the invariant that an aggregate WindowsAppSDK upgrade must never contain a component package downgrade. Covers: - The cross-channel race condition that produces NuGet downgrades (e.g., 2.0.325-experimental > 2.0.300 stable for WinML). - Approaches considered and explicitly rejected (encoding channel into SemVer fields). - Short-term policy until the monobuild cutover: per-component monotonic-version rules, version.json baseline-bump pattern at release-branch creation, aggregator pre-publish downgrade check, and a ~2-week stagger between experimental and stable/servicing aggregate releases. - Long-term: the WindowsAppSDKVersionPinned unified versioning scheme from the monobuild (a single WindowsAppSDKVersion stamped at the top of the aggregator pipeline; Directory.Packages.props floats 2.* for CI/PR/local and pins to the exact version for Official/Nightly). Cross-linked from docs/Coding-Guidelines.md and specs/Deployment/WindowsAppSDKVersioning.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
… anchor Updates the long-term unified versioning strategy references in docs/Coding-Guidelines/ComponentVersioning.md to: - Use the release/main branch on OS/WinAppSDK (instead of release/dev/monobuild) - Link directly to section 9 'Version Management' in Mono-Build-Pipeline-Migration.md via the documented anchor - Standardize on the microsoft.visualstudio.com/OS host Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
… sequencing After team discussion, the staggered-release approach was dropped in favor of a sequencing guarantee: when experimental and stable/servicing aggregate RC builds are scheduled on the same day (or close together), stable/servicing always builds first. Component owners can rely on that sequencing when designing their per-component versioning so per-channel counter advances applied for the experimental build cannot retroactively cause the stable build to ship a lower component version. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
After the monobuild cutover, contributors should declare a milestone alias (e.g. WinAppSDK_2_Servicing) on runtime compatibility / change-ID checks rather than hardcoding a SemVer literal. The monobuild resolves the alias to the concrete version it is producing (e.g. 2.1.0) at build time, so contributors no longer have to anticipate the version their change will land in. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
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
1 participant
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.
Adds an interim contributor guideline at
docs/Coding-Guidelines/ComponentVersioning.md establishing the invariant
that an aggregate WindowsAppSDK upgrade must never contain a component
package downgrade.
Covers:
(e.g., 2.0.325-experimental > 2.0.300 stable for WinML).
SemVer fields).
monotonic-version rules, version.json baseline-bump pattern at
release-branch creation, aggregator pre-publish downgrade check, and
a ~2-week stagger between experimental and stable/servicing aggregate
releases.
from the monobuild (a single WindowsAppSDKVersion stamped at the top
of the aggregator pipeline; Directory.Packages.props floats 2.* for
CI/PR/local and pins to the exact version for Official/Nightly).
Cross-linked from docs/Coding-Guidelines.md and
specs/Deployment/WindowsAppSDKVersioning.md.
Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com