Restarted the production of the app

libs/Catch2/docs/deprecations.md

@@ -0,0 +1,144 @@
+<a id="top"></a>
+# Deprecations and incoming changes
+
+This page documents current deprecations and upcoming planned changes
+inside Catch2. The difference between these is that a deprecated feature
+will be removed, while a planned change to a feature means that the
+feature will behave differently, but will still be present. Obviously,
+either of these is a breaking change, and thus will not happen until
+at least the next major release.
+
+
+## Deprecations
+
+### `--list-*` return values
+
+The return codes of the `--list-*` family of command line arguments
+will no longer be equal to the number of tests/tags/etc found, instead
+it will be 0 for success and non-zero for failure.
+
+
+### `--list-test-names-only`
+
+`--list-test-names-only` command line argument will be removed.
+
+
+### `ANON_TEST_CASE`
+
+`ANON_TEST_CASE` is scheduled for removal, as it can be fully replaced
+by a `TEST_CASE` with no arguments.
+
+
+### Secondary description amongst tags
+
+Currently, the tags part of `TEST_CASE` (and others) macro can also
+contain text that is not part of tags. This text is then separated into
+a "description" of the test case, but the description is then never used
+apart from writing it out for `--list-tests -v high`.
+
+Because it isn't actually used nor documented, and brings complications
+to Catch2's internals, description support will be removed.
+
+### SourceLineInfo::empty()
+
+There should be no reason to ever have an empty `SourceLineInfo`, so the
+method will be removed.
+
+
+### Composing lvalues of already composed matchers
+
+Because a significant bug in this use case has persisted for 2+ years
+without a bug report, and to simplify the implementation, code that
+composes lvalues of composed matchers will not compile. That is,
+this code will no longer work:
+
+```cpp
+            auto m1 = Contains("string");
+            auto m2 = Contains("random");
+            auto composed1 = m1 || m2;
+            auto m3 = Contains("different");
+            auto composed2 = composed1 || m3;
+            REQUIRE_THAT(foo(), !composed1);
+            REQUIRE_THAT(foo(), composed2);
+```
+
+Instead you will have to write this:
+
+```cpp
+            auto m1 = Contains("string");
+            auto m2 = Contains("random");
+            auto m3 = Contains("different");
+            REQUIRE_THAT(foo(), !(m1 || m2));
+            REQUIRE_THAT(foo(), m1 || m2 || m3);
+```
+
+### `ParseAndAddCatchTests.cmake`
+
+The CMake/CTest integration using `ParseAndAddCatchTests.cmake` is deprecated,
+as it can be replaced by `Catch.cmake` that provides the function
+`catch_discover_tests` to get tests directly from a CMake target via the
+command line interface instead of parsing C++ code with regular expressions.
+
+
+## Planned changes
+
+
+### Reporter verbosities
+
+The current implementation of verbosities, where the reporter is checked
+up-front whether it supports the requested verbosity, is fundamentally
+misguided and will be changed. The new implementation will no longer check
+whether the specified reporter supports the requested verbosity, instead
+it will be up to the reporters to deal with verbosities as they see fit
+(with an expectation that unsupported verbosities will be, at most,
+warnings, but not errors).
+
+
+### Output format of `--list-*` command line parameters
+
+The various list operations will be piped through reporters. This means
+that e.g. XML reporter will write the output as machine-parseable XML,
+while the Console reporter will keep the current, human-oriented output.
+
+
+### `CHECKED_IF` and `CHECKED_ELSE`
+
+To make the `CHECKED_IF` and `CHECKED_ELSE` macros more useful, they will
+be marked as "OK to fail" (`Catch::ResultDisposition::SuppressFail` flag
+will be added), which means that their failure will not fail the test,
+making the `else` actually useful.
+
+
+### Change semantics of `[.]` and tag exclusion
+
+Currently, given these 2 tests
+```cpp
+TEST_CASE("A", "[.][foo]") {}
+TEST_CASE("B", "[.][bar]") {}
+```
+specifying `[foo]` as the testspec will run test "A" and specifying
+`~[foo]` will run test "B", even though it is hidden. Also, specifying
+`~[baz]` will run both tests. This behaviour is often surprising and will
+be changed so that hidden tests are included in a run only if they
+positively match a testspec.
+
+
+### Console Colour API
+
+The API for Catch2's console colour will be changed to take an extra
+argument, the stream to which the colour code should be applied.
+
+
+### Type erasure in the `PredicateMatcher`
+
+Currently, the `PredicateMatcher` uses `std::function` for type erasure,
+so that type of the matcher is always `PredicateMatcher<T>`, regardless
+of the type of the predicate. Because of the high compilation overhead
+of `std::function`, and the fact that the type erasure is used only rarely,
+`PredicateMatcher` will no longer be type erased in the future. Instead,
+the predicate type will be made part of the PredicateMatcher's type.
+
+
+---
+
+[Home](Readme.md#top)