build: variables (arg, env)

[dvdksn]

Proposed changes

Adds a new manuals page about build variables (arg, env) highlighting their differences and use.

https://deploy-preview-19386--docsdocker.netlify.app/build/building/variables/

• config: add example node version
• config: fix incorrect example version for alpine
• build: add "build variables" page

Related issues (optional)

• ARG not available in following FROM moby/moby#40830 (comment)

@netlify /build/building/variables/

[netlify]

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	b5032e1
🔍 Latest deploy log	https://app.netlify.com/sites/docsdocker/deploys/65d46a1f48f1150008d705c8
😎 Deploy Preview	https://deploy-preview-19386--docsdocker.netlify.app/build/building/variables
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[thaJeztah]

Oh! Wanted to reply on slack but didn't get to that. I wonder if we could come up with a slightly modified example where the "breakpoint" stages are consecutive in the Dockerfile, i.e. (trying to give it my best ASCII-art here);

FROM alpine:${VERSION} AS stage-1
ARG HELLO=hello
RUN echo $HELLO

..................................

# stage-1-a is a continuation of stage-1, and therefore inherits build-args
# that are defined in it. This stage can be used as a "break-point" within
# the stage-1 stage.
FROM stage-1 AS stage-1-a
ARG WORLD=world
RUN echo $HELLO $WORLD

..................................

# similarly, stage-1-b is a continuation of stage-1-a, and can act as
# another break-point in stage-1 for debugging purposes.
FROM stage-1-a AS stage-1-b
RUN echo $HELLO $WORLD

In the above, we could put all of the stage-1-xxx in a single "box", but with a dotted separator between them perhaps.

[dvdksn]

any blocking issues with this one @thaJeztah or @crazy-max. The illustration could maybe be prettier but I think it gets the message across.

[aevesdocker]

Comment: I've started using a note to do the same thing with Compose.
> Available in ....etc
Perhaps we should agree on a format going forward for the sake of consistency? Which is better?

[dvdksn]

yes we definitely should standardize this. I think we should probably have a shortcode for it like k8s does with feature_state. That would also let us have more control over rendering, and better structure the parameters (possibly even let us specify and test for old versions to be cleaned up after a while). Maybe for a follow-up?

[aevesdocker]

👍 sounds good to me

[thaJeztah]

"+1" on having this kind of information in a more structured form.

I recall we discussed this at some point, and know we have the "API version" annotations for some options, e.g.;

For those we (used to? still have?) a configurable "threshold", which allows use to conditionally render those badges. That way, we can keep the metadata (added in version X), but can decide whether it's still relevant to highlight/show (e.g., highlighting a feature that was added 6 or 7 years ago is no longer very informative).

If we have specific criteria, we could also use that information to automatically render "new" / "what's new" badges, such as what's being added in #19444 (add a "new" badge because it was added for Docker Desktop 4.28, but once we are a couple of version(s) along, we can hide that).