Version Release

Version Release

Use this skill when the user asks to release or prepare an AtomUI version, or review release readiness.

Durable rules, the breaking-change surface list, and the release-readiness checklist live in docs/engineering/workflows/release-preparation.md. Read it before classifying any change.

Workflow

1. Confirm the intended version and release scope from the user request. If the target version or range is ambiguous, state the assumption and proceed with preparation; get explicit confirmation before tag, push, or publish.
2. Inspect repository state before changing files:
   • git status --short
   • git branch --show-current
   • git tag --sort=-v:refname | head
   • git log --oneline --decorate <previous-tag>..HEAD when a previous tag exists
3. Run the breaking-change audit below and write down its verdict before editing any release file. The verdict decides whether migration docs are required.

Breaking-change audit

Publishing a breaking change without migration docs is a release defect. The audit is mandatory, and a "no breaking changes" verdict must be evidenced, never assumed.

1. Enumerate every commit carrying a breaking marker:

   git log <previous-tag>..HEAD --format='%h %s' | grep -E '!:'

   Classify each hit individually. A ! commit is the repository telling you a breaking change exists; it may not be dismissed without evidence.

2. Decide against the consumer-visible surface, not against C# members alone. A change is breaking when it alters any of these, even when no C# public member is removed:

   • C# public API: types, members, signatures, enum values, default behavior.
   • MSBuild contract: build/** properties, targets, UsingTask registration, task parameters, item/property names.
   • Package contract: target frameworks, output layout (tools/, buildTransitive/), package ids, shipped files.
   • Build prerequisites: required SDK/runtime versions, global.json.
   • Runtime contracts: design tokens, theme keys, resource keys, AOT/trimming behavior.

3. Evidence rule. A "not breaking" verdict must positively state which surfaces the change touches and why consumers are unaffected. An empty negation-only check such as grep '^-.*public ' is not evidence: it cannot see MSBuild, packaging, TFM or SDK changes, and must not be presented as a verdict.

4. Precedent check. Whenever a breaking candidate exists, or the change touches build/, packaging, or target frameworks, read the most recent docs/releases/*-api-changes.md and search all of them for the same area:

   grep -rln -iE 'build|packaging|msbuild|netstandard|net10|sdk|tools/' docs/releases/*-api-changes.md

   Build-task and packaging contract changes are documented as API changes in this repository even when no control API moves; see docs/releases/6.1.4-api-changes.md.

5. Record the verdict as a candidate → breaking? → evidence table and report it to the user before requesting the release commit, tag, or push.

Automated breaking-change gates

The manual audit above is backed by two executable gates in the release flow. They observe produced artifacts, not commit messages, so they still catch a break whose commit is missing the ! marker.

• Package API validation: EnablePackageValidation with PackageValidationBaselineVersion, wired in build/PackageValidation.props. Compares the lib/ public API (ApiCompat, IL level) against the previously released packages. It cannot see tools/, buildTransitive/ or the target-framework set.
• Package layout validation: scripts/verification/verify-package-layout.ps1. Compares the consumer-visible package layout (lib/ TFM set, tools/, build/, buildTransitive/) against the previously released packages.

Both run from scripts/BuildNuGetPackages.ps1 when given -PackageValidationBaselineVersion; the release workflow passes it through the PackageValidationBaselineVersion input.

• Run both for the release and report the result. A failing gate is a release defect until the change is either documented as breaking or acknowledged.
• Acknowledge an intentional package API change in build/PackageValidationSuppressions/<ProjectName>.xml (generate with -p:ApiCompatGenerateSuppressionFile=true, then review).
• Acknowledge an intentional package layout change in scripts/verification/package-layout-allowlist.json, keyed by baseline version and package id with a reason. Unused entries fail the gate, so the allow list cannot rot.
• Acknowledging either kind does not replace the migration doc: add the section to docs/releases/<version>-api-changes.md too.

Version consistency

• Keep build/Versions.props -> AtomUIVersion as the single source of truth.
• Packages normally inherit $(AtomUIVersion) through build/PackageMetadata.props. AtomUI.Core embeds it as assembly metadata and PublishToLocal.ps1 reads it. Do not hardcode version strings in project files, package metadata, or scripts.
• Scan for stale previous-version references and update only release-required files.

README version references

README.md and README.zh-CN.md are user-facing release pages and are part of every release. Update both in the same release commit and keep their versions identical. The version appears in four places in each file, and every one must change together:

1. The AtomUI badge near the top: .../badge/AtomUI-<version>-1677ff?....
2. The #### Latest Release Notes (English) / #### 最新版本说明 (Chinese) paragraph: rewrite the summary for this release instead of leaving the previous release's text, mention any breaking changes, and link the changelog.
3. The dotnet add package ... --version <version> block.
4. The <PackageReference ... Version="<version>"/> project example.

Bumping only the badge while the release-notes paragraph still describes the previous version is a release defect. Verify no stale version remains before the release commit:

grep -n "<previous-version>" README.md README.zh-CN.md

Changelog

• Update both CHANGELOG.md and CHANGELOG.zh-CN.md with the same version, release date, and information. Use YYYY-MM-DD dates.
• Group entries by control or module (Dialog, ToolTip, Window, DataGrid, Theme, NativeAOT, Build), not a mechanical Added/Changed/Fixed split.
• Write present-tense user-visible outcomes and include PR or issue references when available.
• Follow docs/engineering/contributing/changelog-guidelines.md.