Document the container image naming and tagging convention #53

Goal

Define and document a clear container image naming and tagging convention for images published from this repository.

The convention must support both stable releases and development images that follow Nextcloud Server master, and it must be reusable by environments that consume these images.

Scope

Add repository documentation that becomes the source of truth for container image names, tags, and traceability.

The documentation must define the different parts of an image identity separately.

Image name

Explain how published image names are formed.

Use the images that this repository actually publishes as the starting point, such as the application and web images.

The naming convention must make it clear which component an image contains without putting version, channel, or runtime information into the image name when that information belongs in the tag.

Do not invent new image types only for the documentation.

Channel or version

Explain how to identify:

• stable release images;
• development images that follow Nextcloud Server master;
• immutable versions or revisions;
• moving aliases that point to the current image of a channel.

Do not use a future Nextcloud major version as the main identity of the development channel. The development channel represents the current upstream master.

Runtime variant

Explain how runtime variants are represented independently from the channel or version.

Examples may include:

• apache;
• fpm.

The convention must allow other runtime variants to be added later without changing the meaning of the version or channel.

Do not document a runtime variant as supported unless it already exists or is part of the architecture defined by the parent Epic.

Moving and immutable tags

Define the difference between:

• moving tags, which may point to a newer image over time;
• immutable tags, which must always identify the same published image.

Document when each type should be used.

Immutable tags must provide enough information to identify the exact build or upstream revision.

Avoid ambiguous tags such as bare latest, dev, or a development image identified only by a Nextcloud major version.

Existing tags such as latest or the current version-specific development tag are implementation details of the current setup. They must not automatically become part of the new convention.

Traceability

Document the metadata that a published image must expose so that the image can be traced back to its sources.

At minimum, define metadata for:

• source repository;
• source revision;
• build date;
• Nextcloud version or revision;
• PHP version;
• runtime variant.

Use standard OCI image labels where an appropriate standard label exists.

If extra project-specific metadata is needed, clearly separate it from standard OCI labels.

Examples

Include a small set of examples showing the convention for:

• a stable image;
• a stable immutable image;
• a development master image;
• an immutable development image;
• different runtime variants where they are relevant.

Base examples on image components that this repository already publishes.

Examples are illustrative. Do not create tag formats that depend on the current Nextcloud 35 implementation.

Documentation location

Keep the documentation in this repository, close to the image build and publishing process.

If no documentation directory exists yet, create a small and clear location for repository documentation and link it from the README.

The documentation should be easy to reference later from AGENTS.md, workflows, and consuming repositories.

Out of scope

This issue is documentation-only.

Do not:

• change existing container image names or tags;
• change Dockerfiles;
• change publishing workflows;
• create new image variants;
• migrate existing image consumers;
• remove the current Nextcloud 35 development image.

Implementation changes will be handled by separate issues after the convention is agreed.

Acceptance criteria

• The documentation defines how image names are formed.
• Existing published image components are used as the basis for naming examples.
• Stable and master channels are defined.
• Moving and immutable tags are clearly distinguished.
• Runtime variants are independent from version/channel naming.
• Ambiguous tag patterns are explicitly discouraged.
• Current historical tags are not treated automatically as the new standard.
• Required traceability metadata is documented.
• OCI standard labels are used where applicable.
• Examples are independent from a specific Nextcloud development major.
• The documentation is linked from the repository README or another clear entry point.

Good first issue

This issue has a limited documentation scope.

If an existing image or consumer does not fit the convention described here, do not change the convention only to preserve the current behavior. Record the case in the pull request and ask for guidance before expanding the scope.