Merge pull request #20564 from dvdksn/build-experimental-checks

build: experimental dockerfile rules

Author: dvdksn

content/manuals/build/checks.md

@@ -212,6 +212,13 @@ argument with a CSV string of check IDs you want to skip. For example:
 $ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=skip=JSONArgsRecommended,StageNameCasing" .
 ```
 
+To skip all checks, use the `skip=all` parameter:
+
+```dockerfile {title=Dockerfile}
+# syntax=docker/dockerfile:1
+# check=skip=all
+```
+
 ## Combine error and skip parameters for check directives
 
 To both skip specific checks and error on check violations, pass both the
@@ -226,3 +233,43 @@ directive in your Dockerfile or in a build argument. For example:
 ```console {title="Build argument"}
 $ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=skip=JSONArgsRecommended,StageNameCasing;error=true" .
 ```
+
+## Experimental checks
+
+Before checks are promoted to stable, they may be available as experimental
+checks. Experimental checks are disabled by default. To see the list of
+experimental checks available, refer to the [Build checks reference](/reference/build-checks/).
+
+To enable all experimental checks, set the `BUILDKIT_DOCKERFILE_CHECK` build
+argument to `experimental=all`:
+
+```console
+$ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=experimental=all" .
+```
+
+You can also enable experimental checks in your Dockerfile using the `check`
+directive:
+
+```dockerfile {title=Dockerfile}
+# syntax=docker/dockerfile:1
+# check=experimental=all
+```
+
+To selectively enable experimental checks, you can pass a CSV string of the
+check IDs you want to enable, either to the `check` directive in your Dockerfile
+or as a build argument. For example:
+
+```dockerfile {title=Dockerfile}
+# syntax=docker/dockerfile:1
+# check=experimental=JSONArgsRecommended,StageNameCasing
+```
+
+Note that the `experimental` directive takes precedence over the `skip`
+directive, meaning that experimental checks will run regardless of the `skip`
+directive you have set. For example, if you set `skip=all` and enable
+experimental checks, the experimental checks will still run:
+
+```dockerfile {title=Dockerfile}
+# syntax=docker/dockerfile:1
+# check=skip=all;experimental=all
+```

data/redirects.yml

@@ -225,6 +225,8 @@
   - /go/build-summary/
 "/desktop/use-desktop/builds/#import-builds":
   - /go/builds-import/
+"/build/checks/#experimental-checks":
+  - "/go/build-checks-experimental/"
 
 # Build links (external)
 "https://www.docker.com/build-early-access-program/?utm_campaign=onboard-30-customer-zero&utm_medium=in-product-ad&utm_source=desktop_v4":