Skip to content

12. Versioning Policy

📋 Versioning Policy#

This framework and its repositories follow a consistent versioning scheme to ensure clarity and compatibility.

Format#

Versions use the format: v<framework_version>_<repository_version>

Both components follow Semantic Versioning (MAJOR.MINOR.PATCH):

  • Framework version: Infrastructure and technical components
  • MAJOR: Breaking changes in framework architecture
  • MINOR: Backward-compatible feature additions

  • PATCH: Bug fixes or minor improvements

  • Repository version: Tutorial content and structure

  • MAJOR: Breaking changes in tutorial content or structure
  • MINOR: New tutorials or enhancements
  • PATCH: Minor corrections or fixes

Examples#

Version Meaning
v1.0.0_1.0.0 Initial release
v1.2.0_1.0.0 Framework upgraded, repository unchanged
v1.2.0_1.1.0 Repository upgraded, framework unchanged
v1.2.5_1.0.3 Framework at 1.2.5, repository at patch 1.0.3

Version Pin#

Each repo pins its framework version in .devcontainer/util/source_framework.sh:

FRAMEWORK_VERSION="${FRAMEWORK_VERSION:-<framework-version>}"

That one line is the single selector: it decides which framework files the container pulls from the cache and which mkdocs-base.yaml the docs workflow fetches. The Sync CLI manages the pin across all repos via push-update.

Read the version from the repo, never from a document

Any version written into a page is stale the next release. To see what a repo actually pins: 

grep -oP ':-\K[^}"]+' .devcontainer/util/source_framework.sh | head -1
Across the whole fleet, sync status shows the drift; the framework's own current version is its latest git tag.

Vendored Front-End Assets#

Mermaid is vendored, not pulled from a CDN at page load. Material for MkDocs would otherwise fetch https://unpkg.com/mermaid@11/dist/mermaid.min.js on every page view — a floating major that can change under the sites without a commit anywhere.
File docs/javascripts/mermaid.min.js
Pinned version 11.17.2
Source https://unpkg.com/mermaid@11.17.2/dist/mermaid.min.js
sha256 581ed7d74bd9048d0e3a91363927d72ef22942d7722546b27f7cc29e35390eb8
Size 3.5 MB raw (0.9 MB gzipped over the wire)

Consuming repos do not commit the file. Their deploy-ghpages.yaml fetches it from this repo at their pinned FRAMEWORK_VERSION, alongside mkdocs-base.yaml and docs/stylesheets/extra.css. The pin therefore travels with the framework version — every repo on the same tag renders with the same mermaid.

The pin does not update itself

There are no automatic security or bug fixes. A diagram written against mermaid syntax newer than the pin renders as an error box in the page; it does not fail the build.

Bumping the pin#

  1. Check what changed upstream: mermaid releases.
  2. Download and record the new hash: 
    curl -fsSL "https://unpkg.com/mermaid@<NEW>/dist/mermaid.min.js" -o docs/javascripts/mermaid.min.js
sha256sum docs/javascripts/mermaid.min.js
  3. Update the version, source URL and sha256 in the extra_javascript comment block of mkdocs-base.yaml, and the table above.
  4. Build and confirm a diagram still renders — mkdocs build succeeding is not proof. Check that the page emits <pre class="mermaid"> and that a diagram appears in the browser. Material puts the rendered SVG in a closed shadow root, so document.querySelector(".mermaid svg") finds nothing even when the diagram is fine.
  5. Release a framework version and sync push-update, so every repo moves to the same mermaid. Repos left on older tags keep the mermaid of the tag they are pinned to.
  6. Bump the Enablement App to the same build, so a diagram that draws on the site also draws in the app: its package.json pins mermaid exactly and commits the same file as ui/assets/vendor/mermaid.min.js (mermaidAsset.test.ts there fails until pin and file agree). The app draws diagrams in mermaid's strict security level — see Diagrams in the app.

Staying inside mermaid 11.x is deliberate: Material 9.5.x asks for mermaid@11, so the pin matches what it expects. A major bump needs a Material upgrade checked alongside it.

Tagging Workflow#

After syncing all repos to a framework version and merging PRs:

# Create combined tags on all repos
sync tag --framework-version <framework-version>

# Bump repo version and create GitHub Releases
sync tag --framework-version <framework-version> --bump patch --release

Benefits#

  • Clarity: Immediate visibility of framework and repository versions
  • Compatibility: Aligns with SemVer and tooling expectations
  • Flexibility: Independent evolution of framework and repositories
  • Automation: Sync CLI manages version bumps, tags, and releases across all repos