From 921f54fb18d2fdc541b30c3e256cdfcb2226a8a8 Mon Sep 17 00:00:00 2001
From: Fernandez Ludovic <ldez@users.noreply.github.com>
Date: Fri, 21 Nov 2025 04:27:06 +0100
Subject: [PATCH] docs: add experimental inside readme

---
 README.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/README.md b/README.md
index 9551bf4..4d6e8b3 100644
--- a/README.md
+++ b/README.md
@@ -275,6 +275,7 @@ You will also likely need to add the following `.gitattributes` file to ensure t
 | [`skip-save-cache`](#skip-save-cache)                         | Don't save cache.                                  |
 | [`cache-invalidation-interval`](#cache-invalidation-interval) | Number of days before cache invalidation.          |
 | [`problem-matchers`](#problem-matchers)                       | Forces the usage of the embedded problem matchers. |
+| [Experimental](#experimental)                                 | Experimental options                               |
 
 ### Installation
 
@@ -552,6 +553,47 @@ with:
 
 </details>
 
+### Experimental
+
+The following options are experimental: those may or may not be supported in the future, and so they will be either converted into a dedicated option or removed.
+
+List of comma-separated options.
+
+<details>
+<summary>Example</summary>
+
+```yaml
+uses: golangci/golangci-lint-action@v9
+with:
+  experimental: "foo,bar"
+```
+
+</details>
+
+#### `automatic-module-directories`
+
+(optional)
+
+This option will run golangci-lint in each module directory, useful for monorepos.
+
+The automatic detection of modules uses the `working-directory` as the base directory if defined, otherwise the root directory.
+
+> [!IMPORTANT]
+> - The cache key will refer to the `working-directory` (if defined) because all the golangci-lint runs must use the same cache directory/key.
+> - The version detection will only work if the project has a single module.
+> - If the project has multiple modules, the custom build file must be located in the repository root ( or `working-directory`).
+
+<details>
+<summary>Example</summary>
+
+```yaml
+uses: golangci/golangci-lint-action@v9
+with:
+  experimental: "automatic-module-directories"
+```
+
+</details>
+
 ## Annotations
 
 Currently, GitHub parses the action's output and creates [annotations](https://github.blog/2018-12-14-introducing-check-runs-and-annotations/).