Skip to content

ReleaseChecklist.md

Latest commit

 

History

History
99 lines (73 loc) · 3.58 KB

ReleaseChecklist.md

File metadata and controls

99 lines (73 loc) · 3.58 KB

Release Checklist

Use this checklist before tagging a public SwiftUsdShell release.

Boundary Audit

Run:

scripts/audit-public-surface.sh

This checks that:

  • SwiftUsdShell stays free of runtime and C++ interop imports
  • tests exercise the base shell without importing the OpenUSD adapter
  • package-local path dependencies are not committed
  • the OpenUSD product dependency and C++ interop setting remain isolated to the adapter target
  • public docs and source do not mention internal project or product names
  • removed renderer/workflow graph concepts do not re-enter the shell

Base Contract Tests

Run:

swift build --target SwiftUsdShell
swift test --filter SwiftUsdShellTests

These should not require building the OpenUSD adapter. If SwiftPM starts building the OpenUSD module for this step, stop and inspect the package graph: the base test target should depend only on SwiftUsdShell.

Adapter Validation

Run the adapter build separately:

swift build --target SwiftUsdShellOpenUSD

This can be expensive because it builds the SwiftUsd/OpenUSD module. Treat adapter compile failures as implementation issues in SwiftUsdShellOpenUSD, not as reasons to move runtime details into SwiftUsdShell.

Public Surface Review

Before tagging:

  • confirm README.md, Docs/Architecture.md, Docs/AdapterCoverage.md, and Docs/ConsumerGuide.md match the actual package surface
  • confirm pending adapter gaps are listed in Docs/AdapterCoverage.md
  • confirm new DTOs are Codable, Hashable, and Sendable unless explicitly documented otherwise
  • confirm new APIs are product-neutral USD contracts, not editor workflow policy

Versioning

Patch releases are appropriate for:

  • documentation changes
  • non-breaking adapter implementation fixes
  • additive convenience initializers that preserve ABI/source compatibility

Minor releases are appropriate for:

  • new public DTOs
  • new runtime protocol requirements
  • new generic edit request cases
  • new adapter coverage that exposes additional shell contract fields

Avoid breaking public DTO shapes without a deliberate major-version plan.

Binary slice coherence (xcframework distribution)

When producing the SwiftUsdShell-binaries / SwiftUsd-binaries xcframeworks via OpenUSDKit's build_swiftusdshell_macos_arm64_binary_slice.sh:

  • Always build from a clean scratch (CLEAN_SCRATCH=1, the default). A reused incremental .build can ship a compiled .swiftmodule that is stale relative to the freshly emitted .swiftinterface. Swift loads the compiled module and ignores the interface, so the published binary advertises API in its text interface that the loaded module does not actually contain. This shipped once as 0.3.124-macos-arm64.2 (interface had blockAttribute / usdaLiteral, module did not).
  • Verify coherence before publishing: the compiled module must expose every symbol the interface advertises. Spot-check by compiling a trivial consumer that references the newest additions against the produced xcframework.
  • Distribution follows a single coordinated release train across both binary repos with exact pins only. See OpenUSDKit/docs/decisions/0003-binary-distribution-release-train.md and Reality2713/OpenUSDKit#13.
  • When an edit atom changes stage lifetime or persistence semantics, publish a new coordinated train and validate it through at least one downstream app scheme. 0.3.126-macos-arm64.3 is the reference case: cached stage ownership, save, and reload were validated by Deconstructed's InspectorUI SwiftPM target and macOS Xcode app scheme.