Add deprecations documentation

docs/Readme.md

@@ -36,3 +36,4 @@ Other:
 * [Open Source Projects using Catch](opensource-users.md#top)
 * [Contributing](contributing.md#top)
 * [Release Notes](release-notes.md#top)
+* [Deprecations](deprecations.md#top)

docs/deprecations.md

@@ -0,0 +1,50 @@
+<a id="top"></a>
+# Deprecations and incoming changes
+
+**Contents**<br>
+[Verbosities](#verbosities)<br>
+[`--list-*` command line parameters](#--list--command-line-parameters)<br>
+[Types passed to the reporter interface](#types-passed-to-the-reporter-interface)<br>
+[Generators](#generators)<br>
+
+This page documents current deprecations and upcoming changes inside
+Catch2. You can expect deprecated functionality to stick around until
+the next major release, but not for longer.
+
+
+## Verbosities
+
+The current implementation of verbosities has been misguided and will
+be removed. Note that this does not mean verbosities will be gone, just
+that they will no longer be checked up-front, and a reporter can handle
+verbosity however it sees fit (including ignoring it).
+
+
+## `--list-*` command line parameters
+
+There will be 3 large changes to the `--list-*` family of command line
+parameters.
+
+* Their return codes will no longer reflect the number of tests/tags/etc
+that were found, instead it will be 0 for success and non-zero for failure.
+* Their output will be piped through reporters, so that e.g. XML reporter
+will write the output as a machine-readable XML, while the console
+reporter will keep the current output.
+* `--list-test-names-only` will be completely removed.
+
+
+## Types passed to the reporter interface
+
+To allow changes in internal representation, we are planning to change
+the arguments provided to functions in the reporter interface.
+
+
+## Generators
+
+The current generator interface is not intended to be stable and will be
+changed.
+
+
+---
+
+[Home](Readme.md#top)