COPY note for --exclude feels/is misleading

[the-noob]

Is this a docs issue?

• My issue is about the documentation content or website

Type of issue

Information is incorrect

Description

The note about not being available in stable syntax seems in contradiction with https://docs.docker.com/reference/dockerfile/#copy which states 'from 1.7-labs' (implying that 1.8 has this syntax)

https://docs.docker.com/reference/dockerfile/#copy---exclude

Location

https://docs.docker.com/reference/dockerfile/

Suggestion

No response

[thaJeztah]

Thanks for reporting!

So the version scheme for these is that docker/dockerfile:x.y.z-labs is equivalent to docker/dockerfile:x.y.z (stable) plus the "labs" features enabled (also see https://docs.docker.com/build/buildkit/frontend/). In some cases, a feature will be in labs, and moved to stape with the next release, but this is not always the case; sometimes a feature needs more feedback, or needs refinements before it enters the stable channel. In some (rare) ocassion, it's possible for a labs feature to be changed, or even removed if it didn't meet the standards for the stable channel (although I don't think this happened), I think this was originally a motivator for including (minor) versions for features still in labs, so that a Dockerfile using the feature would continue to function even if a later version would remove it.

I agree though that mentioning the version here (where a later stable version is available) can be somewhat confusing (we had some disussions around similar cases); given that it's very rare for the feature to be removed, in a later version, perhaps it's better to list these as docker/dockerfile:1-labs (maybe with a footnote (first introduced in labs v1.x.y))

@crazy-max @colinhemmings WDYT?

[the-noob]

Thanks for the detailed explanation! My initial thought was that x.y-labs makes it into x.(y+1) automatically (i.e 1.7-labs is included in 1.8)
Meanwhile, I figured out the -labs bit, I never saw the https://docs.docker.com/build/buildkit/frontend/ page and the explanation there. Indeed, my bad, but sometimes I tend to forget what I was doing by 'open in a new tab' every reference, so I'm trying to fight that.

Maybe change the options listing table to something like

Option	Minimum Dockerfile Version	Labs
--from
--chown
--chmod	1.2
--link	1.4
--parents	N/A	1.7-labs
--exclude	N/A	1.7-labs

And once it makes it into stable the N/A can be updated (and labs reference removed ?)

[thaJeztah]

Thanks! Yes, I (personally) think a table like that could help.

In general, I tend to avoid mentioning versions too much (at least in examples), because in my experience, users copy/paste the example, and never think of updating their Dockerfile again, so now locked themselves into an old version of the Dockerfile syntax (either labs or stable), and never receive updates and bug fixes.

There's definitely situations where that's desired (pin to a fixed version, and only update when needed), but it's also really easy to forget updating 😅 (and now being confused "why does this example from the docs not work in MY Dockerfile?").

[the-noob]

Coincidently, that's exactly how I ended up raising this issue.
We had an 'oldish' Dockerfile that used --exclude and Renovate suggested updating to 1.(x+3)-labs and I though "ah, latest version is 1.12 (back then), which is > 1.7-labs, I'll use that".
Let's see what others think about the table.