From 04a3b89a673f1b737a51f5d84b3095d8ea5345f7 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Wed, 23 Oct 2024 16:35:52 +0200
Subject: [PATCH] docs: update undefined var check reference

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 .../dockerfile/docs/rules/undefined-var.md    | 33 ++++++++++++-------
 .../dockerfile/linter/docs/UndefinedVar.md    | 33 ++++++++++++-------
 2 files changed, 44 insertions(+), 22 deletions(-)

diff --git a/frontend/dockerfile/docs/rules/undefined-var.md b/frontend/dockerfile/docs/rules/undefined-var.md
index 037e16bd239ff..decbecb29a44a 100644
--- a/frontend/dockerfile/docs/rules/undefined-var.md
+++ b/frontend/dockerfile/docs/rules/undefined-var.md
@@ -13,24 +13,21 @@ Usage of undefined variable '$foo'
 
 ## Description
 
-Before you reference an environment variable or a build argument in a `RUN`
-instruction, you should ensure that the variable is declared in the Dockerfile,
-using the `ARG` or `ENV` instructions.
+This check ensures that environment variables and build arguments are correctly
+declared before being used in the following instructions: `ADD`, `ARG`, `COPY`,
+`ENV`, and `FROM`. While undeclared variables might not cause an immediate
+build failure, they can lead to unexpected behavior or errors later in the
+build process.
 
-Attempting to access an environment variable without explicitly declaring it
-doesn't necessarily result in a build error, but it may yield an unexpected
-result or an error later on in the build process.
-
-This check also attempts to detect if you're accessing a variable with a typo.
-For example, given the following Dockerfile:
+It also detects common mistakes like typos in variable names. For example, in
+the following Dockerfile:
 
 ```dockerfile
 FROM alpine
 ENV PATH=$PAHT:/app/bin
 ```
 
-The check detects that `$PAHT` is undefined, and that it's probably a
-misspelling of `PATH`.
+The check identifies that `$PAHT` is undefined and likely a typo for `$PATH`:
 
 ```text
 Usage of undefined variable '$PAHT' (did you mean $PATH?)
@@ -53,3 +50,17 @@ ARG foo
 COPY $foo .
 ```
 
+❌ Bad: `$foo` is undefined.
+
+```dockerfile
+FROM alpine AS base
+ARG VERSION=$foo
+```
+
+✅ Good: the base image defines `$PYTHON_VERSION`
+
+```dockerfile
+FROM python AS base
+ARG VERSION=$PYTHON_VERSION
+```
+
diff --git a/frontend/dockerfile/linter/docs/UndefinedVar.md b/frontend/dockerfile/linter/docs/UndefinedVar.md
index a2ee68559df56..f60fbe2941e16 100644
--- a/frontend/dockerfile/linter/docs/UndefinedVar.md
+++ b/frontend/dockerfile/linter/docs/UndefinedVar.md
@@ -6,24 +6,21 @@ Usage of undefined variable '$foo'
 
 ## Description
 
-Before you reference an environment variable or a build argument in a `RUN`
-instruction, you should ensure that the variable is declared in the Dockerfile,
-using the `ARG` or `ENV` instructions.
+This check ensures that environment variables and build arguments are correctly
+declared before being used in the following instructions: `ADD`, `ARG`, `COPY`,
+`ENV`, and `FROM`. While undeclared variables might not cause an immediate
+build failure, they can lead to unexpected behavior or errors later in the
+build process.
 
-Attempting to access an environment variable without explicitly declaring it
-doesn't necessarily result in a build error, but it may yield an unexpected
-result or an error later on in the build process.
-
-This check also attempts to detect if you're accessing a variable with a typo.
-For example, given the following Dockerfile:
+It also detects common mistakes like typos in variable names. For example, in
+the following Dockerfile:
 
 ```dockerfile
 FROM alpine
 ENV PATH=$PAHT:/app/bin
 ```
 
-The check detects that `$PAHT` is undefined, and that it's probably a
-misspelling of `PATH`.
+The check identifies that `$PAHT` is undefined and likely a typo for `$PATH`:
 
 ```text
 Usage of undefined variable '$PAHT' (did you mean $PATH?)
@@ -45,3 +42,17 @@ FROM alpine AS base
 ARG foo
 COPY $foo .
 ```
+
+❌ Bad: `$foo` is undefined.
+
+```dockerfile
+FROM alpine AS base
+ARG VERSION=$foo
+```
+
+✅ Good: the base image defines `$PYTHON_VERSION`
+
+```dockerfile
+FROM python AS base
+ARG VERSION=$PYTHON_VERSION
+```