Documentation Currency Review — 2026-11-18
Tracking issue: NCAT #718.
Baseline and scope
The latest published stable template reviewed for this change is
2.11.10.
The repository can prepare a newer package on main without changing the
identity of the latest published release.
The main documentation tree inventory contains 86 files: 67 Markdown
sources, three YAML navigation files, and 16 JSON, JavaScript, CSS, template,
image, or other resource files. The inventory covers:
| Area | Review treatment |
|---|---|
docs/index.md, docs/articles/index.md, docs/toc.yml, docs/articles/toc.yml |
Current landing, navigation, and release discovery |
docs/articles/template-packaging.md |
Published install pins, package identity and generated options |
docs/articles/ runtime guides |
Authentication, authorization, middleware, EF Core, audit/outbox, telemetry, deployment, and operational boundaries |
docs/articles/ release and repository guidance |
Build quality, container publishing, workflow and security controls |
docs/articles/release-notes-*.md |
Version-specific release evidence; preserve release identities |
docs/articles/v1-migration-guide.md and docs/articles/asibackbone-6-alignment-review.md |
Explicit historical migration and integration records |
docs/adr/ |
Dated architecture decisions, not statements that an older release is currently published |
docs/api/ and docs/api-pages/ |
Generated API entry points and namespace navigation; inspect source-generated output in DocFX validation |
docs/examples/, docs/public/, docs/templates/, docs/images/ |
Configuration examples, site presentation, and binary resources rather than package-release claims |
The review checked version-related prose and searched current-facing guidance
for older release assertions. Technical claims were compared with
Directory.Build.props, the template package identity, the version-consistency
validator, the release-update workflow, and the current publishing documents.
This is not a claim of independent, line-by-line security certification of
every documented runtime behavior.
Findings and decisions
- Homepage: The previous “Latest GitHub release” link concealed the reviewed version. The homepage now names the published release and links directly to its release record and matching documentation release notes.
- Package install: The published package table and
dotnet new installcommand already used 2.11.10; preserve these as a reproducible published baseline rather than replacing them with a future prepared repository version. - Automatic update: After each release, the release-update PR must update the homepage and published package examples together with README and SUPPORT.
- Validation:
Validate-VersionConsistency.ps1now checks the published homepage row, release notes, packaging version, and pinned installation examples against the latest published README marker. - Evergreen guidance: Keep runtime and operational documentation version-neutral unless a version is essential to an implementation boundary.
- Historical material: Preserve the v1 migration guide, historical AsiBackbone 6 integration review, release notes, ADRs, package identity introduction history, intentionally pinned configurations and schema/wire version identifiers.
Organization documentation context
Equivalent sources were considered in the other organization repositories:
AsiBackbone/AsiBackbone (governance package), Learning (teaching snapshots
and pinned baselines), ReferenceApplication (integration-reviewed pins),
.github (compatibility and assurance records), and asibackbone.github.io
(organization landing). Those repositories own their own runtime, educational,
and compatibility claims. This patch intentionally changes only NCAT files.
Validation and publication follow-up
Run before merging:
./scripts/Validate-VersionConsistency.ps1
./scripts/Validate-LandingPage.ps1 -SelfTest
Also run repository CI, relevant template packaging/scaffold tests, DocFX build, and documentation/link validation. Those jobs require the complete toolchain and are not recorded as passed by this review.
After the documentation workflow publishes, verify live
/NetCoreApplicationTemplate/ HTML and the Template Packaging page. Compare
their displayed release and install command with the actual published stable
GitHub Release. Do not treat search-index snippets as deployed truth.
Separate follow-up: validate additional runtime and security claims against each owning implementation and its tests when those contracts change; do not automatically replace legitimate historical references with newer numbers.
Follow-up completed
The post-publication check this review called for is now automated (#718).
scripts/Test-PublishedReleaseReferences.ps1 checks the generated homepage and
Template Packaging page before deployment, and the Verify published release references job checks the deployed pages after each publication, separating
deployment lag, HTTP failures, missing markers, and version mismatches. See
Documentation Publishing.
On 2026-11-18, after #719 was published, the live homepage showed current release
2.11.10 with its release-notes link, and the live Template Packaging page showed
package version 2.11.10 with the published-versus-candidate note, matching the
README Current Release block. Repository CI, version consistency, documentation
link validation, and documentation publishing all passed on the #719 merge commit.