Merge pull request moby#5451 from dvdksn/check-jsonargs-recommend

docs: add workarounds for JSONArgsRecommended check

Author: tonistiigi

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.
 

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.