Proposal: org.opencontainers.image.base.source

[kaaax0815]

Add org.opencontainers.image.base.source as a Pre-Defined Annotation Key.

Why

Many projects don't maintain their own Dockerfiles and respective packages. Thats why packaging groups like linuxserver.io¹ exist. These groups maintain a Dockerfile for that project and publish them. They set org.opencontainers.image.source to their own repo, which is correct as they host the code to "build the image"².

Tools like Renovate³ use the org.opencontainers.image.source labe to fetch metadata and changelogs ⁴. The problems lies with fetching the changelogs from there. Most often packaging groups follow the upstream release cycle as close as possible and therefore don't have their own changelog

Adding org.opencontainers.image.base.source as a pre-defined annotation key would clearly separate the image build source from the upstream project source. This allows packaging groups to correctly reference their Dockerfile repositories while still pointing tools like Renovate to the true upstream project for metadata and changelogs.

Footnotes

1. https://www.linuxserver.io/ ↩

2. https://github.com/opencontainers/image-spec/blob/main/annotations.md#pre-defined-annotation-keys ↩

3. https://www.mend.io/renovate/ ↩

4. https://docs.renovatebot.com/modules/datasource/docker/#description ↩

[sudo-bmitch]

This has a lot of parallels with #1046 where the concerns I have are with standardizing any one tool into OCI. The annotations we standardize are agnostic to any specific image build tooling. So if, for example, a project needs to standardize the location of a Dockerfile, that would be a docker specific annotation, outside of the scope of OCI. In this case, you may need a linuxserver.io specific annotation since they perform builds differently than many other projects.

I'd also push this specific problem into two other areas. One is to package and attach an SBOM, and then have tooling check all of the SBOM contents for any dependency that has been upgraded. The Dockerfile and embedded repository may be unchanged, but a package installed from a package manager could have changed. Which gets to my second direction: reproducible builds. If the output of a build is always reproducible because everything is pinned in the Dockerfile, then any changes downstream would get picked up as a commit to the Dockerfile.

[kaaax0815]

So if, for example, a project needs to standardize the location of a Dockerfile, that would be a docker specific annotation, outside of the scope of OCI.

But its not meant to specify the dockerfile location. this is kept vague intentionally, so many tools can use it.

In this case, you may need a linuxserver.io specific annotation since they perform builds differently than many other projects.

but all repos that create a container image from another repo, have a upstream, therefore this applies to almost all cases

If the output of a build is always reproducible because everything is pinned in the Dockerfile, then any changes downstream would get picked up as a commit to the Dockerfile.

i don't think this matters for this proposal. its just meant to point to the upstream, not which exact version, as packagers handle that on their own

[sudo-bmitch]

So if, for example, a project needs to standardize the location of a Dockerfile, that would be a docker specific annotation, outside of the scope of OCI.

But its not meant to specify the dockerfile location. this is kept vague intentionally, so many tools can use it.

It's an example, pointing to how OCI treats implementation specific requests, even when the implementation is a rather popular one.

In this case, you may need a linuxserver.io specific annotation since they perform builds differently than many other projects.

but all repos that create a container image from another repo, have a upstream, therefore this applies to almost all cases

This is a very specific implementation that doesn't mirror what we see in the greater ecosystem. More broadly, this is trying to define an annotation with a single value for a 0 to $n field. Some implementations may not have any upstream dependencies, vendoring everything. Other projects may have multiple upstream dependencies, and have already been documenting that with an SBOM. At least the first case could not set this field, but there's single correct value when a project has multiple upstream dependencies that wouldn't eventually break due to manifest size limits.

If the output of a build is always reproducible because everything is pinned in the Dockerfile, then any changes downstream would get picked up as a commit to the Dockerfile.

i don't think this matters for this proposal. its just meant to point to the upstream, not which exact version, as packagers handle that on their own

This problem exists because you have builds pointing to a mutable upstream dependency. If that wasn't the case, upstream changelogs could be vendored into your own releases.

[kaaax0815]

Some implementations may not have any upstream dependencies, vendoring everything.

then they don't have to use that annotation (which is true . but its not meant for dependencies, which should be recorded in sbom. but for people packaging projects that don't publish docker images on their own.

yes when people package multiple projects into one, this wouldn't fit that case.

This problem exists because you have builds pointing to a mutable upstream dependency. If that wasn't the case, upstream changelogs could be vendored into your own releases.

most often the builds point to a specific commit/tag in the upstream, but its not only about changelogs

If you disagree with the proposal, which it seems like, this pr should be closed