From 17bf946c729323cdc214904437b60e694b816455 Mon Sep 17 00:00:00 2001
From: Voyagerroc-Code <325343927+Voyagerroc-Code@users.noreply.github.com>
Date: Sun, 13 Sep 2026 20:33:54 +0300
Subject: [PATCH] docs: define container image tagging convention

---
 README.md             |  4 +++
 docs/image-tagging.md | 58 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+)
 create mode 100644 docs/image-tagging.md

diff --git a/README.md b/README.md
index fe8db26..7a4e5a5 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,10 @@ Languages avaliable: [pt-BR](docs/README_ptBR.md)
 
 # Nextcloud with SSL and Docker
 
+See [Container image naming and tags](docs/image-tagging.md) for the image
+components, release channels, runtime variants, immutable tags, and traceability
+metadata.
+
 - [Nextcloud with SSL and Docker](#nextcloud-with-ssl-and-docker)
   - [Setup of docker](#setup-of-docker)
   - [Setup of proxy](#setup-of-proxy)
diff --git a/docs/image-tagging.md b/docs/image-tagging.md
new file mode 100644
index 0000000..1a58ea4
--- /dev/null
+++ b/docs/image-tagging.md
@@ -0,0 +1,58 @@
+# Container image naming and tags
+
+This repository publishes two image components from the same source tree:
+
+- `ghcr.io/librecodecoop/nextcloud-docker-app`
+- `ghcr.io/librecodecoop/nextcloud-docker-web`
+
+The component belongs in the image name. The release channel, upstream version,
+revision, and runtime variant belong in the tag or image metadata.
+
+## Channels
+
+Stable images use the Nextcloud release version as the channel tag, for example
+`app:31` or `app:31.0.4`. A major tag is moving and follows the latest compatible
+patch release. A full version tag is immutable after publication.
+
+Development images follow the current Nextcloud `master` branch. Use `master`
+as the moving channel tag, and use `master-<short-revision>` as the immutable
+tag for a specific upstream revision. A development image must not identify
+itself only by a future Nextcloud major version.
+
+Avoid bare `latest` and bare `dev` tags for new consumers because neither
+identifies a release channel or upstream source clearly.
+
+## Runtime variants
+
+Runtime variants are independent of the channel. When a component has more than
+one supported runtime, append it to the component tag, for example `31-apache`
+and `31-fpm`. This leaves the version and channel meaning unchanged when another
+variant is added.
+
+## Traceability
+
+Every published image should expose OCI labels for:
+
+- `org.opencontainers.image.source`: this repository;
+- `org.opencontainers.image.revision`: the source commit;
+- `org.opencontainers.image.created`: the build timestamp;
+- `org.opencontainers.image.version`: the Nextcloud version or `master` revision;
+- `org.opencontainers.image.base.name`: the runtime base image.
+
+The image tag selects a channel or an immutable build. OCI labels explain the
+exact source and build inputs, so consumers can audit a running image without
+guessing from its tag.
+
+## Examples
+
+```text
+ghcr.io/librecodecoop/nextcloud-docker-app:31
+ghcr.io/librecodecoop/nextcloud-docker-app:31.0.4
+ghcr.io/librecodecoop/nextcloud-docker-app:master
+ghcr.io/librecodecoop/nextcloud-docker-app:master-a1b2c3d
+ghcr.io/librecodecoop/nextcloud-docker-web:31-apache
+ghcr.io/librecodecoop/nextcloud-docker-web:master-fpm
+```
+
+The examples describe the convention only. This change does not rename existing
+images, alter tags, or change the publishing workflows.