Deprecate `build_always`, add `build_always_stale`

Since `build_always` also adds a target to the set of default targets,
this option is marked deprecated in favour of the new option
`build_always_stale`.

`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 still be achieved by combining
`build_always_stale` with `build_by_default`.

fixes #1942

1 files changed, 12 insertions, 0 deletions

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.