NiaDocs
3.5.0
Menu

Nia documentation · 3.5.0

Documentation versions

Understand latest documentation, immutable release snapshots and the complete next-release candidate.

nia-todo versions API, administrator and user documentation together. Every published app release has one complete documentation snapshot using the same full semantic version.

Latest documentation

/docs/latest/ is a virtual pointer to the newest successfully promoted release snapshot. Stable links such as /docs, /docs/api, and /docs/setup resolve to that same snapshot.

latest changes only after the public GitHub release exists, its exact tag has been validated, and the Forgejo-side promotion checks pass. It never represents an unreleased development state.

Immutable release snapshots

Published snapshots use full versions such as /docs/v3.1.1/. Each registry entry records the matching app tag and commit, the source documentation commit, and a SHA-256 content hash.

A snapshot is never silently overwritten. A new app release receives a new snapshot even when its documentation content is unchanged; Git stores identical files efficiently while the metadata preserves the exact release history.

The complete next candidate

next is always a complete documentation tree, not a list of changed pages. Immediately after a promotion it is content-identical to the new release snapshot and becomes the starting point for the following release.

When documentation changes, next/.release.json must name the target release, mark the affected documentation areas as reviewed, and set ready to true. If documented application areas changed but the text did not, the manifest must instead contain an explicit no-impact review and reason.

Forgejo-side promotion

The private Forgejo workflow checks the public GitHub Releases API every 30 minutes. GitHub never calls Forgejo and holds no Forgejo credentials.

When a newer release appears, Forgejo checks out its exact public tag, compares changed application areas, validates API route coverage against next, creates the immutable snapshot, and builds the complete website. Validation or build failures stop before deployment. Promotion metadata is committed only after a successful deployment; a failed final push is retried by the next scheduled run.

Version selector

The selector keeps the current page when that page exists in the selected snapshot. If an older version does not contain it, the selector opens that version’s documentation home instead of linking to a missing page.