From a302dd1f0bae664e97caa2c407edd208145f5553 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Thu, 24 Oct 2024 11:33:30 +0200
Subject: [PATCH] docs: add workarounds for JSONArgsRecommended check

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 .../docs/rules/json-args-recommended.md       | 39 +++++++++++++++++--
 .../linter/docs/JSONArgsRecommended.md        | 39 +++++++++++++++++--
 2 files changed, 70 insertions(+), 8 deletions(-)

diff --git a/frontend/dockerfile/docs/rules/json-args-recommended.md b/frontend/dockerfile/docs/rules/json-args-recommended.md
index 1f6c785b2ec4..e832233025ac 100644
--- a/frontend/dockerfile/docs/rules/json-args-recommended.md
+++ b/frontend/dockerfile/docs/rules/json-args-recommended.md
@@ -50,10 +50,41 @@ Note that running programs as PID 1 means the program now has the special
 responsibilities and behaviors associated with PID 1 in Linux, such as reaping
 child processes.
 
-Alternatively, if you want to ignore this lint rule because you do want your
-executable to be invoked via a shell, you can use the
-[`SHELL`](https://docs.docker.com/reference/dockerfile/#shell) Dockerfile
-instruction to explicitly specify a shell to use.
+### Workarounds
+
+There might still be cases when you want to run your containers under a shell.
+When using exec form, shell features such as variable expansion, piping (`|`)
+and command chaining (`&&`, `||`, `;`), are not available. To use such
+features, you need to use shell form.
+
+Here are some ways you can achieve that. Note that this still means that
+executables run as child-processes of a shell.
+
+#### Create a wrapper script
+
+You can create an entrypoint script that wraps your startup commands, and
+execute that script with a JSON-formatted `ENTRYPOINT` command.
+
+✅ Good: the `ENTRYPOINT` uses JSON format.
+
+```dockerfile
+FROM alpine
+RUN apk add bash
+COPY --chmod=755 <<EOT /entrypoint.sh
+#!/usr/bin/env bash
+set -e
+my-background-process &
+my-program start
+EOT
+ENTRYPOINT ["/entrypoint.sh"]
+```
+
+#### Explicitly specify the shell
+
+You can use the [`SHELL`](https://docs.docker.com/reference/dockerfile/#shell)
+Dockerfile instruction to explicitly specify a shell to use. This will suppress
+the warning since setting the `SHELL` instruction indicates that using shell
+form is a conscious decision.
 
 ✅ Good: shell is explicitly defined.
 
diff --git a/frontend/dockerfile/linter/docs/JSONArgsRecommended.md b/frontend/dockerfile/linter/docs/JSONArgsRecommended.md
index cb9bb5780ee5..cd0a83967f0c 100644
--- a/frontend/dockerfile/linter/docs/JSONArgsRecommended.md
+++ b/frontend/dockerfile/linter/docs/JSONArgsRecommended.md
@@ -43,10 +43,41 @@ Note that running programs as PID 1 means the program now has the special
 responsibilities and behaviors associated with PID 1 in Linux, such as reaping
 child processes.
 
-Alternatively, if you want to ignore this lint rule because you do want your
-executable to be invoked via a shell, you can use the
-[`SHELL`](https://docs.docker.com/reference/dockerfile/#shell) Dockerfile
-instruction to explicitly specify a shell to use.
+### Workarounds
+
+There might still be cases when you want to run your containers under a shell.
+When using exec form, shell features such as variable expansion, piping (`|`)
+and command chaining (`&&`, `||`, `;`), are not available. To use such
+features, you need to use shell form.
+
+Here are some ways you can achieve that. Note that this still means that
+executables run as child-processes of a shell.
+
+#### Create a wrapper script
+
+You can create an entrypoint script that wraps your startup commands, and
+execute that script with a JSON-formatted `ENTRYPOINT` command.
+
+✅ Good: the `ENTRYPOINT` uses JSON format.
+
+```dockerfile
+FROM alpine
+RUN apk add bash
+COPY --chmod=755 <<EOT /entrypoint.sh
+#!/usr/bin/env bash
+set -e
+my-background-process &
+my-program start
+EOT
+ENTRYPOINT ["/entrypoint.sh"]
+```
+
+#### Explicitly specify the shell
+
+You can use the [`SHELL`](https://docs.docker.com/reference/dockerfile/#shell)
+Dockerfile instruction to explicitly specify a shell to use. This will suppress
+the warning since setting the `SHELL` instruction indicates that using shell
+form is a conscious decision.
 
 ✅ Good: shell is explicitly defined.