3 files changed, 22 insertions, 5 deletions

diff --git a/docs/markdown/Configuration.md b/docs/markdown/Configuration.md
index 48f071e6c..b5875e55e 100644
--- a/docs/markdown/Configuration.md
+++ b/docs/markdown/Configuration.md
@@ -39,7 +39,7 @@ use a single `configuration_data` object as many times as you like,
 but it becomes immutable after being passed to the `configure_file`
 function. That is, after it has been used once to generate output the
 `set` function becomes unusable and trying to call it causes an error.
-Copy of immutable `configuration_data` is still immutable.
+*Since 1.5.0* Copy of immutable `configuration_data` is however mutable.
 
 For more complex configuration file generation Meson provides a second
 form. To use it, put a line like this in your configuration file.
diff --git a/docs/yaml/objects/cfg_data.yaml b/docs/yaml/objects/cfg_data.yaml
index 03abb1709..069cadbf6 100644
--- a/docs/yaml/objects/cfg_data.yaml
+++ b/docs/yaml/objects/cfg_data.yaml
@@ -1,10 +1,14 @@
 name: cfg_data
 long_name: Configuration data object
 description: |
-  This object encapsulates
-  configuration values to be used for generating configuration files. A
-  more in-depth description can be found in the [the configuration wiki
-  page](Configuration.md).
+  This object encapsulates configuration values to be used for generating
+  configuration files. A more in-depth description can be found in the
+  [the configuration page](Configuration.md).
+
+  This object becomes immutable after first use. This means that
+  calling set() or merge_from() will cause an error if this object has
+  already been used in any function arguments. However, assignment creates a
+  mutable copy.
 
 methods:
 - name: set
diff --git a/docs/yaml/objects/env.yaml b/docs/yaml/objects/env.yaml
index 714da4fe4..3b2e2a851 100644
--- a/docs/yaml/objects/env.yaml
+++ b/docs/yaml/objects/env.yaml
@@ -9,6 +9,11 @@ description: |
   on the same `varname`. Earlier Meson versions would warn and only the last
   operation took effect.
 
+  *Since 1.5.0* This object becomes immutable after first use. This means that
+  calling append(), prepend() or set() will cause a deprecation warning if this
+  object has already been used in any function arguments. However, assignment
+  creates a mutable copy.
+
 example: |
   ```meson
   env = environment()
@@ -18,6 +23,14 @@ example: |
   env.append('MY_PATH', '2')
   env.append('MY_PATH', '3')
   env.prepend('MY_PATH', '0')
+
+  # Deprecated since 1.5.0
+  run_command('script.py', env: env)
+  env.append('MY_PATH', '4')
+
+  # Allowed and only env2 is modified
+  env2 = env
+  env2.append('MY_PATH', '4')
   ```
 
 methods: