From ff4fa29d5e26464cb4c43c6cef12476ce989ef53 Mon Sep 17 00:00:00 2001 From: joey-huckabee <138994589+joey-huckabee@users.noreply.github.com> Date: Thu, 10 Sep 2026 07:55:13 -0500 Subject: [PATCH] docs: include UBI major in release tags --- .github/ISSUE_TEMPLATE/bug.yml | 2 +- CHANGELOG.md | 13 ++++---- README.md | 10 +++--- docs/DEPLOYMENT.md | 2 +- docs/ROADMAP.md | 5 +-- docs/VERSION.md | 37 ++++++++++++---------- docs/examples/systemd/nginx-ubi9.container | 2 +- 7 files changed, 40 insertions(+), 31 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml index fc5dbc5..2ba35ad 100644 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -14,7 +14,7 @@ body: attributes: label: Image tag and digest description: Include both when available; do not report only a mutable tag. - placeholder: ghcr.io/datopsis/nginx-ubi9:v...@sha256:... + placeholder: ghcr.io/datopsis/nginx-ubi:v1.30.4-ubi9-r20260908.1@sha256:... validations: required: true - type: input diff --git a/CHANGELOG.md b/CHANGELOG.md index fd0caa8..8be9d48 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,9 +21,9 @@ but container releases use the upstream-derived format documented in - Defined the forward-looking first-release roadmap and evidence lifecycle. - Defined independent versioning for container releases and repository-only revisions. -- Adopted NGINX-version plus UTC release-date versioning, removed the UBI minor - version from release tags, and prohibited mutable convenience tags for the - first release. +- Adopted NGINX-version, UBI-major, and UTC release-date versioning; omitted + the UBI minor version from release tags; and prohibited mutable convenience + tags for the first release. - Added the project overview, intended use cases, security design, rootless runtime model, and release status. - Added pinned local pre-commit checks for repository hygiene, shell code, @@ -81,9 +81,10 @@ but container releases use the upstream-derived format documented in ### Changed -- Renamed the source repository from `nginx-ubi9` to `nginx-ubi` so repository - identity does not prevent future work on other UBI major versions; existing - image, service, and UBI 9 identifiers remain unchanged. +- Renamed the source repository and planned GHCR image from `nginx-ubi9` to + `nginx-ubi` so their identities do not prevent future work on other UBI major + versions; UBI 9-specific service and development identifiers remain + unchanged. - Upgraded the reference contributor environment from Ubuntu 22.04.5 and Podman 3.4.4 to Ubuntu 24.04.5 and Podman 5.8.2, verified the restricted runtime and Quadlet lifecycle after a cold WSL restart, and retired the diff --git a/README.md b/README.md index 1e4ddee..d3ef836 100644 --- a/README.md +++ b/README.md @@ -123,20 +123,22 @@ their associated implementations and evidence are developed. The planned image location is: ```text -ghcr.io/datopsis/nginx-ubi9 +ghcr.io/datopsis/nginx-ubi ``` Container releases will use annotated tags in this form: ```text -v-r. +v-ubi-r. ``` Image releases and repository revisions are deliberately separate. Production deployments should pin an immutable OCI digest. Repository-only changes are identified by their full Git commit SHA and do not receive source-only release -tags. The UBI minor version is recorded in digest-bound release evidence rather -than the tag because it does not uniquely identify the final filesystem. +tags. The UBI major version is part of the tag because it identifies the +runtime product line. The UBI minor version is recorded in digest-bound release +evidence rather than the tag because it does not uniquely identify the final +filesystem. ## Development status diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index b450e89..dcdd61e 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -84,7 +84,7 @@ or pull the exact digest. The service definition deliberately uses `Pull=never` so startup cannot silently replace the approved artifact. ```console -IMAGE='ghcr.io/datopsis/nginx-ubi9@sha256:' +IMAGE='ghcr.io/datopsis/nginx-ubi@sha256:' podman pull "$IMAGE" podman image inspect "$IMAGE" ``` diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 34e4d7d..ea11cca 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -197,8 +197,9 @@ local evaluation but is not yet a supported release. ## Package 7: signed first release - [ ] Implement and test the approved - `v-r.` tag contract, UTC date and - sequence validation, immutable release and commit tags, and OCI metadata. + `v-ubi-r.` tag contract, + NGINX and UBI version matching, UTC date and sequence validation, immutable + release and commit tags, and OCI metadata. - [ ] Define the first-release support lifetime and superseded-release policy. - [ ] Freeze the final upstream versions and digests only after image-affecting work is complete. diff --git a/docs/VERSION.md b/docs/VERSION.md index a4f2711..69c382a 100644 --- a/docs/VERSION.md +++ b/docs/VERSION.md @@ -10,12 +10,13 @@ supports. Annotated release tags use: ```text -v-r. +v-ubi-r. ``` -For example, `v1.30.4-r20260908.1` would identify: +For example, `v1.30.4-ubi9-r20260908.1` would identify: - NGINX `1.30.4`; +- the UBI 9 runtime product line; - a Datopsis container release created on 2026-09-08 UTC; and - the first container release created on that UTC date. @@ -23,17 +24,19 @@ The `r` distinguishes this project's container release from an upstream NGINX source or package version. The eight-digit date is the UTC date on which the immutable release tag is created. The sequence is a positive integer beginning at `1` and increments for every additional container release created on the -same UTC date, regardless of NGINX version. Dates must not be backdated. +same UTC date, regardless of NGINX or UBI major version. Dates must not be +backdated. This upstream-derived format is not Semantic Versioning. The downstream release suffix communicates release chronology; it does not claim API-compatibility semantics for NGINX configuration. -The tag deliberately omits the UBI minor version. Package updates can make the -runtime filesystem newer than the original base-image snapshot, and a named -minor version does not identify exact bytes. The repository name establishes -the UBI 9 product line. The exact UBI reference and digest remain required in -OCI metadata, the SBOM, provenance, and release evidence. +The tag includes the UBI major version because changing that version changes +the runtime product line and its compatibility and support boundary. It +deliberately omits the UBI minor version: package updates can make the runtime +filesystem newer than the original base-image snapshot, and a named minor +version does not identify exact bytes. The exact UBI reference and digest +remain required in OCI metadata, the SBOM, provenance, and release evidence. Release tags are immutable. Never move or reuse a release tag. Production deployments should pin the OCI digest; a human-readable tag describes a @@ -42,13 +45,13 @@ release, while its digest identifies exact image content. The release workflow must accept only tags matching: ```regex -^v[0-9]+\.[0-9]+\.[0-9]+-r[0-9]{8}\.[1-9][0-9]*$ +^v[0-9]+\.[0-9]+\.[0-9]+-ubi[1-9][0-9]*-r[0-9]{8}\.[1-9][0-9]*$ ``` Pattern matching is only the first check. The workflow must also validate a -real UTC calendar date, the selected NGINX version, the daily sequence against -existing immutable tags, and that the tagged commit is the protected `main` -release commit. +real UTC calendar date, the selected NGINX version, the selected UBI major +version, the daily sequence against existing immutable tags, and that the +tagged commit is the protected `main` release commit. ## Artifact identity @@ -70,7 +73,8 @@ The image digest, not any label or tag, is the definitive artifact identity. | Change | Version action | | --- | --- | | Change the NGINX version | Use the new NGINX version with the release date and next sequence for that UTC date. | -| Change the UBI reference or digest | Keep the NGINX field and create a release using the current UTC date and next daily sequence. | +| Change the UBI major version | Use the new UBI major field with the NGINX version, current UTC date, and next daily sequence. | +| Change only the UBI minor reference or digest | Keep the NGINX and UBI major fields and create a release using the current UTC date and next daily sequence. | | Change an RPM, dependency lock, runtime behavior, default configuration, entrypoint, build input, or release metadata | Create a release using the current UTC date and next daily sequence. | | Deliberately rebuild otherwise unchanged inputs | Create a release using the current UTC date and next daily sequence. | | Change only documentation, tests, development tooling, policies, examples not copied into the image, issue templates, or analysis workflows | Do not create or change a container release version unless an image is deliberately republished. | @@ -83,7 +87,7 @@ daily sequence; never fill an older gap or reuse a failed or withdrawn tag. The first release publishes only: -- the immutable release tag, such as `v1.30.4-r20260908.1`; and +- the immutable release tag, such as `v1.30.4-ubi9-r20260908.1`; and - an immutable `sha-` traceability tag. Mutable tags such as `latest`, `stable`, `1`, or `1.30` are not published. @@ -114,8 +118,9 @@ previous release without claiming every entry changed the image filesystem. Before an annotated release tag is pushed: -1. Verify that the tag's NGINX version matches the locked RPM and that release - metadata records the exact UBI reference and digest. +1. Verify that the tag's NGINX version matches the locked RPM, that its UBI + major version matches the locked base images, and that release metadata + records the exact UBI reference and digest. 2. Convert `Unreleased` changelog entries into a dated section for the tag and create a new empty `Unreleased` section. 3. Complete the applicable release gates in `docs/ROADMAP.md`. diff --git a/docs/examples/systemd/nginx-ubi9.container b/docs/examples/systemd/nginx-ubi9.container index ac9b6a1..0acdf94 100644 --- a/docs/examples/systemd/nginx-ubi9.container +++ b/docs/examples/systemd/nginx-ubi9.container @@ -6,7 +6,7 @@ Description=Datopsis rootless NGINX container Documentation=https://github.com/datopsis/nginx-ubi9 [Container] -Image=ghcr.io/datopsis/nginx-ubi9@sha256: +Image=ghcr.io/datopsis/nginx-ubi@sha256: Pull=never ContainerName=nginx-ubi9 User=999:0