2 files changed, 16 insertions, 2 deletions
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index f75030f..bab20e1 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -232,9 +232,11 @@ following.
 - `build_by_default` *(added 0.38.0)* causes, when set to true, to
   have this target be built by default, that is, when invoking plain
   `ninja`; the default value is false
-- `build_always` if `true` this target is always considered out of
+- `build_always` (deprecated) if `true` this target is always considered out of
   date and is rebuilt every time, useful for things such as build
-  timestamps or revision control tags
+  timestamps or revision control tags.
+- `build_always_stale` if `true` the target is always considered out of date.
+  The associated command is run even if the outputs are up to date.
 - `capture`, there are some compilers that can't be told to write
   their output to a file but instead write it to standard output. When
   this argument is set to true, Meson captures `stdout` and writes it
diff --git a/docs/markdown/snippets/deprecate_build_always.md b/docs/markdown/snippets/deprecate_build_always.md
new file mode 100644
index 0000000..d6e54b5
--- /dev/null
+++ b/docs/markdown/snippets/deprecate_build_always.md
@@ -0,0 +1,12 @@
+## Deprecate `build_always`
+
+Setting `build_always` to `true` for a custom target not only marks the target
+to be always considered out of date, but also adds it to the set of default
+targets. This option is therefore deprecated and the new option
+`build_always_stale` is introduced.
+
+`build_always_stale` *only* marks the target to be always considered out of
+date, but does not add it to the set of default targets. The old behaviour can
+be achieved by combining `build_always_stale` with `build_by_default`.
+
+The documentation has been updated accordingly.