Model versioning and redirects

Use this guide when one product starts needing latest-release, development, archive, or release-specific routes without changing public permalinks by hand.

Start with public URL policy

Decide which public route families the site should preserve, for example:

  • latest-release routes
  • development routes
  • exact release routes
  • archive or withdrawn release routes

The important rule is that public routing is consumer-owned policy. It should not be inferred accidentally from repository names or source layout.

Select version contexts explicitly

An artifact combines source-control discovery rules, authored lifecycle data, and publication selection. This example publishes development docs, every authored maintenance-line head, and the latest release in each line:

 1artifacts:
 2  - key: runtime
 3    source: runtime
 4    versioning:
 5      developmentRef: main
 6      tagPattern: ^v.*$
 7    publicationSelection:
 8      development: true
 9      lineHeads:
10        mode: allAuthored
11      releases:
12        mode: latestPerLine
13    lifecycle:
14      releaseLines:
15        - key: "4.0"
16          maintenanceRef: maintenance/4.0
17          latest: "4.0.0"
18      releases:
19        - version: "4.0.0"

The matching provider snapshot records supply the resolved main, maintenance/4.0, and v4.0.0 contexts. The authored catalog still owns which of those contexts are published and where they appear.

Distinguish routes, aliases, and redirects

  • A published or context route identifies content that exists at a public path.
  • An alias is another public route for the same target.
  • A redirect tells the deployment layer to send one request URL to another resolved target.

For example, add a redirect when an old development-docs entry point should now lead to the exact release:

1publication:
2  mountPath: /spark/
3  redirects:
4    - fromPath: /spark/development/docs/
5      target: release:spark/runtime@4.0.0
6      status: 308
7      reason: Current docs live on the latest release route.

Typed targets such as release:spark/runtime@4.0.0 keep the destination tied to the resolved publication model. Use route:/path/ when the public route itself is the intended target, or a fully qualified URL for an external destination.

Allowed redirect statuses are 301, 302, 307, and 308. Choose the status as part of publication policy; downstream adapters should preserve it.

Build and inspect the resolved result

1site-pipeline check
2site-pipeline build

The route aggregate should contain the selected contexts:

1/spark/development/
2/spark/development/4.0/
3/spark/releases/4.0.0/

The redirect aggregate should contain a resolved entry like this:

1{
2  "fromUrl": "https://docs.example.org/spark/development/docs/",
3  "toUrl": "https://docs.example.org/spark/releases/4.0.0/",
4  "status": 308,
5  "reason": "Current docs live on the latest release route.",
6  "sourceKind": "catalog"
7}

Use routes.json to understand route ownership and canonical/alias state. Use redirects.json to generate concrete server or edge behavior.

Failure cases to resolve before deployment

  • A typed target must refer to a selected component, artifact, line, release, or route.
  • fromPath must belong to the declared origin and must not conflict with published content.
  • Alias and canonical paths must resolve without ambiguous ownership.
  • Provider records must agree with the authored version, tag, ref, and publication state.
  • A deployment adapter must not rebuild or reinterpret redirect destinations from request-derived host values.

Read this next

For unreleased development contract details: