From b658039162ca44f2dbdd2fac4ed034331605e78a Mon Sep 17 00:00:00 2001
From: Weihang Lo <me@weihanglo.tw>
Date: Tue, 25 Nov 2025 12:20:18 -0500
Subject: [PATCH 1/3] docs(config-include): clarify merge behavior a bit

---
 src/doc/src/reference/unstable.md | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md
index 78564ed5b15..6fa3ec7b7cc 100644
--- a/src/doc/src/reference/unstable.md
+++ b/src/doc/src/reference/unstable.md
@@ -698,11 +698,12 @@ fields are supported:
 
 The merge behavior of `include` is different from other config values:
 
-1. Config values are first loaded from the `include` path.
-    * If `include` is an array, config values are loaded and merged from left
-      to right for each path.
+1. Config values are first loaded from the `include` paths.
+    * Included files are loaded left to right,
+      with values from later files taking precedence over earlier ones.
     * This step recurses if included config files also contain `include` keys.
-2. Then, the config file's own values are merged on top of the included config.
+2. Then, the config file's own values are merged on top of the included config,
+   taking highest precedence.
 
 ## target-applies-to-host
 * Original Pull Request: [#9322](https://github.com/rust-lang/cargo/pull/9322)

From cf7b53a2e04986cf09eeecb42a5e9eb645b56451 Mon Sep 17 00:00:00 2001
From: Weihang Lo <me@weihanglo.tw>
Date: Tue, 25 Nov 2025 12:18:47 -0500
Subject: [PATCH 2/3] docs(config-include): emphasize inline table syntax

Discussed in 2025-11-25 t-cargo meeting.
We prefer inline tables over array of tables for `include`.

* `include` is special and should appear early in config files,
  before other configuration keys
* Array-of-tables syntax allows interleaving with other config,
  which creates confusion about merge order and precedence
* Inline tables keep all `include` declarations together at the top,
  making the load order and override behavior clearer
---
 src/doc/src/reference/unstable.md | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md
index 6fa3ec7b7cc..35b3d9336b2 100644
--- a/src/doc/src/reference/unstable.md
+++ b/src/doc/src/reference/unstable.md
@@ -662,8 +662,9 @@ rustflags = ["-W", "unsafe-code"]
 
 #### `include`
 
-* Type: array of strings, or array of tables
+* Type: array of strings or tables
 * Default: none
+* Environment: not supported
 
 Loads additional config files. Paths are relative to the config file that
 includes them. Only paths ending with `.toml` are accepted.
@@ -672,25 +673,24 @@ Supports the following formats:
 
 ```toml
 # array of paths
-include = ["frodo.toml", "samwise.toml"]
-
-# inline tables
 include = [
-    "simple.toml",
-    { path = "optional.toml", optional = true }
+    "frodo.toml",
+    "samwise.toml",
 ]
 
-# array of tables
-[[include]]
-path = "required.toml"
-
-[[include]]
-path = "optional.toml"
-optional = true
+# inline tables for more control
+include = [
+    { path = "required.toml" },
+    { path = "optional.toml", optional = true },
+]
 ```
 
-When using table syntax (inline tables or array of tables), the following
-fields are supported:
+> **Note:** For better readability and to avoid confusion, it is recommended to:
+> - Place `include` at the top of the configuration file
+> - Put one include per line for clearer version control diffs
+> - Use inline table syntax when optional includes are needed
+
+When using table syntax, the following fields are supported:
 
 * `path` (string, required): Path to the config file to include.
 * `optional` (boolean, default: false): If `true`, missing files are silently

From 18eae1663578549045335eb9d2a8128ba4bb052b Mon Sep 17 00:00:00 2001
From: Weihang Lo <me@weihanglo.tw>
Date: Tue, 25 Nov 2025 12:24:15 -0500
Subject: [PATCH 3/3] docs(config-include): prepare for doc stabilization

This adds introductory section explaining purpose
as well as one placement note for stabilization
---
 src/doc/src/reference/unstable.md | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md
index 35b3d9336b2..fcab1f6e134 100644
--- a/src/doc/src/reference/unstable.md
+++ b/src/doc/src/reference/unstable.md
@@ -660,14 +660,24 @@ rustflags = ["-W", "unsafe-code"]
 
 ### Documentation updates
 
-#### `include`
+> put this after `## Command-line overrides` before `## Config-relative paths`
+> to emphasize its special nature than other config keys.
+
+#### Including extra configuration files
+
+Configuration can include other configuration files using the top-level `include` key.
+This allows sharing configuration across multiple projects
+or splitting complex configurations into multiple files.
+
+##### `include`
 
 * Type: array of strings or tables
 * Default: none
 * Environment: not supported
 
-Loads additional config files. Paths are relative to the config file that
-includes them. Only paths ending with `.toml` are accepted.
+Loads additional configuration files.
+Paths are relative to the configuration file that includes them.
+Only paths ending with `.toml` are accepted.
 
 Supports the following formats: