Improve docs about ARG in FROM

[dnephin]

See docker/for-linux#59 and moby/moby#31352 (comment) and moby/moby#34008

[codecov-io]

Codecov Report

Merging #333 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #333   +/-   ##
=======================================
  Coverage   48.85%   48.85%           
=======================================
  Files         186      186           
  Lines       12413    12413           
=======================================
  Hits         6064     6064           
  Misses       5975     5975           
  Partials      374      374

[tonistiigi]

Maybe better to mention that every stage has individual args, then it is better to understand that "arg-in-from" is not an exception but just follows the rule.

How about this example:

ARG VERSION=latest
FROM busybox:$VERSION
ARG VERSION
RUN echo $VERSION > image_version

[mdlinville]

Maybe something like "An ARG instructions is only relevant for the next FROM instruction that comes after it in the Dockerfile, and then using this example to illustrate that.

[dnephin]

Maybe something like "An ARG instructions is only relevant for the next FROM instruction that comes after it in the Dockerfile,

That's not exactly correct. There are two cases:

• any ARG before the first FROM can be used in any FROM line
• any ARG within a build stage (after a FROM) can be used in that build stage

I can add more details to the ARG reference section as well (this stuff is under FROM) , but I think this line needs to be updated as well something along the lines of what I have.

[mdlinville]

Maybe something like "An ARG instructions is only relevant for the next FROM instruction that comes after it in the Dockerfile, and then using this example to illustrate that.

[dnephin]

I've updated to include more details, and added some more structure to the ARG section, PTAL

[tonistiigi]

The text lgtm but the examples could be better. The image_version example was specifically for the case where it may make sense to use the same variable in FROM and inside the stage. I would switch the examples and make "arg-in-from" use the image_version and arguments in multiple stages use ARG SETTINGS.

[dnephin]

Makes sense, I've swapped the examples.

[tonistiigi]

LGTM

[thaJeztah]

LGTM, thanks!