From f018aec0e57b606178855013e8905e80c3672277 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Thu, 8 Aug 2024 18:52:23 +0200
Subject: [PATCH] build: experimental dockerfile rules

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 content/manuals/build/checks.md | 47 +++++++++++++++++++++++++++++++++
 data/redirects.yml              |  2 ++
 2 files changed, 49 insertions(+)

diff --git a/content/manuals/build/checks.md b/content/manuals/build/checks.md
index 3c4cb1b576..1ee5eda9e2 100644
--- a/content/manuals/build/checks.md
+++ b/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
+```
diff --git a/data/redirects.yml b/data/redirects.yml
index 2c7e4a4b5d..530f1aff22 100644
--- a/data/redirects.yml
+++ b/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":