HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-version-tracking.md

Boilerplate Version Tracking

Purpose

This guide defines how maintainers and downstream projects record the boilerplate baseline they adopted, how they review drift from that baseline, and how they preserve upgrade evidence without inventing runtime migrations. It complements the SemVer policy in docs/versioning.md, the upgrade path in docs/upgrade.md, release entries in docs/releases/README.md, the migration registry in docs/migration-registry.md, the documentation porting guide in docs/porting-guide.md, post-port verification in docs/porting-verification.md, and the public CHANGELOG.md.

Version tracking is documentation evidence. It proves that a downstream project recorded a reviewed source version, release entry, drift review, and verification summary; it is not package publish proof, artifact provenance, deployment proof, or migration execution proof unless it links to immutable artifact, tag, or deployment evidence that is separately reviewed and redacted.

SemVer source version

The source boilerplate version is the upstream boilerplate release that downstream work starts from or last reconciled against. Use the SemVer decision rules in docs/versioning.md and the matching release note in CHANGELOG.md before classifying a baseline as patch, minor, or major.

Record the source version with placeholder-only fields such as:

Field	Safe placeholder format	Notes
Source version label	<source-version-label>	Example shape only; use the released SemVer label when the record is finalized.
Source release entry path	<docs/releases/vMAJOR.MINOR.PATCH.md>	Link to a local release entry under docs/releases/README.md when available.
Source changelog heading	<CHANGELOG.md#version-heading>	The heading must match CHANGELOG.md.
Source commit SHA label	<source-commit-sha-label>	Store a short or full SHA label only after it is public to the project and safe to disclose.
Source artifact label	<artifact-or-tag-label>	Optional; do not imply artifact proof unless the tag, digest, or signed artifact record exists.

Do not use this record to claim that a package was published, an image was pushed, a database migration ran, or a production deployment succeeded. Those claims require their own immutable evidence and manual runtime notes where applicable.

Tracked fields

Each downstream baseline record should include these fields with redacted, placeholder-only values until the release owner fills them with safe evidence:

Field	Required value	Redaction rule
Downstream project label	<downstream-project-label>	Use a generic project label, not a tenant, customer, or private domain.
Downstream baseline version	<downstream-baseline-version>	Name the adopted boilerplate SemVer label or reviewed release train.
Adopted release entry	<docs/releases/release-entry.md>	Use a resolvable local Markdown link when the entry exists.
Changelog alignment	<changelog-entry-label>	Point to the Keep a Changelog entry that describes the baseline.
Commit SHA label	<commit-sha-label>	Record the label only; avoid private repository URLs with credentials.
Migration registry IDs	<migration-registry-id-list>	Use IDs from docs/migration-registry.md; do not invent runtime database migrations for docs-only drift.
Drift review status	<drift-review-status>	Summarize whether downstream differences are accepted, pending review, or blocked.
Verification command names	<verification-command-list>	Name supported non-E2E commands only.
Manual runtime status	<manual-runtime-status>	State whether manual runtime review is not required, pending, passed, failed, or separately recorded.
Rollback note label	<rollback-note-label>	Link to release or deployment rollback notes when the baseline affects runtime behavior.

Allowed values are labels, local file paths, command names, release names, registry IDs, and redacted statuses. Prohibited values include secrets, URLs with credentials, UUID-like deploy endpoints, tenant identifiers, customer identifiers, provider payloads, raw environment values, cookies, bearer tokens, private registry credentials, database connection strings, Redis connection strings, webhook secrets, and screenshots containing sensitive data.

Downstream version ledger

Downstream projects should keep one ledger row per adopted source baseline or material drift review. The ledger belongs in downstream documentation, while this guide defines the contract it should follow.

Suggested ledger shape:

Field	Value
Record ID	<version-record-id>
Source version label	<source-version-label>
Downstream baseline version	<downstream-baseline-version>
Adopted release entry	<docs/releases/release-entry.md>
Commit SHA label	<commit-sha-label>
Migration registry IDs	<migration-registry-id-list>
Drift review status	<drift-review-status>
Verification command names	<verification-command-list>
Manual runtime status	<manual-runtime-status>
Rollback note label	<rollback-note-label>

A ledger row may be marked complete only when its links resolve, its SemVer classification matches docs/versioning.md, its changelog reference matches CHANGELOG.md, and its release entry or downstream handoff notes explain any manual runtime boundary.

Changelog alignment

Every baseline record must point back to an adopted release entry and the corresponding changelog entry. Use docs/releases/README.md for release-entry structure and CHANGELOG.md for the public release summary.

Alignment means:

• Breaking changes in the baseline have migration steps, rollback limits, and verification evidence.
• Minor and patch changes do not silently introduce downstream work outside their SemVer class.
• Empty Keep a Changelog categories remain explicit instead of using unfinished marker text.
• Drift review notes explain whether downstream differences are accepted local customizations or pending upgrade work.
• Release artifact or tag references are immutable labels when they are used as proof.

Version records must not replace release notes. They are an index that lets downstream maintainers find the source release, compare local drift, and decide which upgrade notes apply.

Update workflow

Use this workflow whenever a downstream project adopts a new boilerplate baseline or refreshes drift against an existing baseline:

1. Confirm the source release and SemVer class using docs/versioning.md and CHANGELOG.md.
2. Confirm the adopted release entry under docs/releases/README.md and capture only a local release-entry path or release label.
3. Compare downstream documentation and runtime boundaries against docs/porting-guide.md and docs/porting-verification.md.
4. Review any migration or docs-only tracking IDs in docs/migration-registry.md.
5. Record the drift review status, verification command names, and manual runtime status using placeholder-safe labels.
6. Run supported automatic non-E2E checks when the files exist and the package manager is pinned through pnpm@10.33.0.
7. Link rollback notes from the release entry, upgrade guide, or downstream handoff record when runtime behavior, data, deployment, or security posture can be affected.

Supported automatic checks for this documentation contract are:

pnpm run verify:release-docs
pnpm run verify:docs-links

These checks are local, static, non-E2E verification. They do not drive a browser, open provider consoles, run live deployments, push registries, or prove production readiness.

Downstream project handoff

A downstream handoff should include a short baseline summary, the ledger row, the chosen upgrade path, and the evidence boundary. The handoff should tell the next maintainer what was adopted, what drift remains, which release entry governs the change, and which checks were automatic versus manual.

Minimum handoff content:

• Source boilerplate version label and downstream baseline version.
• Adopted release entry path and changelog entry label.
• Migration registry ID list or a clear statement that no runtime migration registry entry applies.
• Drift review status with accepted local differences separated from pending upgrade work.
• Verification command names, exit status labels, and redacted diagnostic labels.
• Manual runtime status, owner label, and date label when manual review is required.
• Rollback note label that names whether rollback is redeploy-only, migration-sensitive, backup-dependent, or unsupported.

The handoff must avoid tenant names, customer names, private hostnames, provider request payloads, raw environment values, tokens, passwords, and URLs that embed credentials. If a downstream operator needs those values, reference the environment-owned secret store by role label rather than copying values into Markdown.

Compatibility with SemVer/changelog/release entries

The version ledger is compatible with SemVer, changelog, and release-entry records because it stores references rather than redefining policy. docs/versioning.md defines the meaning of major, minor, and patch. CHANGELOG.md gives the public release summary. docs/releases/README.md defines the operator evidence expected around the release.

If these sources disagree, do not finalize the downstream baseline. Correct the release documentation first, then update the version record. For example, a downstream record cannot classify a breaking database behavior change as patch if the versioning policy requires a major release decision and rollback notes.

Migration-registry relationship

Version tracking may reference migration registry IDs from docs/migration-registry.md, but it does not create migrations by itself. Documentation-only baseline records should stay marked as docs evidence unless a real database, deployment, configuration, API, worker, provider, or security migration exists.

Use migration registry IDs for ownership, status, rollback, and verification labels. Use the version ledger for adopted baseline and drift history. When a migration is runtime-affecting, the registry owns the migration detail and this guide should only link the ID and summarize the redacted status.

Upgrade and rollback notes

Upgrade notes should point to docs/upgrade.md, the adopted release entry, and any downstream handoff record. They should explain whether the downstream project is adopting a patch, minor, or major baseline and whether additional drift work is required before rollout.

Rollback notes must state the safest known path:

• Redeploy a prior immutable artifact or tag when no data or configuration migration changed.
• Restore from backup or forward-fix when database state changed and downgrade is not automatic.
• Pause or drain worker queues when queue behavior affects safe rollback.
• Treat provider, security, and mail changes as manual runtime concerns with redacted request or status labels only.

Do not present a version record as rollback proof. It is a pointer to the release and upgrade evidence that defines rollback behavior.

Redacted evidence

Record only safe, reviewable evidence:

• Version labels, release-entry paths, changelog labels, migration registry IDs, and command names.
• Commit SHA labels and artifact or tag labels that are safe for the project to disclose.
• Exit code labels, pass or fail labels, redacted diagnostic codes, and manual runtime status labels.
• Owner role labels and date labels when downstream policy requires them.

Do not record secrets, URLs with credentials, UUID-like deploy endpoints, tenant identifiers, customer identifiers, customer data, provider payloads, raw environment values, cookies, bearer tokens, API keys, private registry credentials, database URLs, Redis URLs, webhook token paths, or full environment dumps.

If evidence arrives with sensitive values, redact it before adding it to the ledger. If redaction would remove the fact needed to prove the claim, link to an approved secure evidence store by role label and keep only the non-secret status in Markdown.

Non-E2E verification

The verifier from the Release Docs release-documentation slice rejects missing required tracking terms, unresolved local links, forbidden placeholder markers, automatic browser or E2E command recommendations, and secret-shaped values. Documentation-only verification reads Markdown locally and does not need runtime services.

For this guide, use:

test -s docs/boilerplate-version-tracking.md
grep -n "^## Tracked fields" docs/boilerplate-version-tracking.md
pnpm run verify:release-docs
pnpm run verify:docs-links

Browser journeys, Playwright, Cypress, provider-console checks, live Docker runs, registry pushes, Coolify execution, production deploys, and customer-impacting request paths are manual runtime evidence only unless a human explicitly approves the exact focused run. When manual review is needed, record the manual runtime status, owner role, target label, immutable tag or request label, and redacted outcome only.