From: David Wells <drwells@email.unc.edu>
Date: Sun, 14 Feb 2021 23:34:07 +0000 (-0500)
Subject: Better document early deprecation.
X-Git-Tag: v9.3.0-rc1~453^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F11750%2Fhead;p=dealii.git

Better document early deprecation.
---

diff --git a/cmake/checks/check_01_cxx_features.cmake b/cmake/checks/check_01_cxx_features.cmake
index 53a43942b1..7e395b70df 100644
--- a/cmake/checks/check_01_cxx_features.cmake
+++ b/cmake/checks/check_01_cxx_features.cmake
@@ -28,6 +28,7 @@
 #   DEAL_II_HAVE_CXX17_LEGENDRE_FUNCTIONS
 #   DEAL_II_FALLTHROUGH
 #   DEAL_II_DEPRECATED
+#   DEAL_II_DEPRECATED_EARLY
 #   DEAL_II_CONSTEXPR
 #
 
diff --git a/doc/news/changes/minor/20210105DanielArndt b/doc/news/changes/minor/20210105DanielArndt
new file mode 100644
index 0000000000..494e3bbff4
--- /dev/null
+++ b/doc/news/changes/minor/20210105DanielArndt
@@ -0,0 +1,12 @@
+New: The policy under which things in deal.II are deprecated has changed.
+Deprecated features are now first marked with DEAL_II_DEPRECATED_EARLY until the
+next release of the library, at which point they will be remarked with
+DEAL_II_DEPRECATED. By default, things marked with DEAL_II_DEPRECATED_EARLY do
+not print deprecation warnings - this is controlled with the
+DEAL_II_EARLY_DEPRECATIONS CMake configuration option. This change was made so
+that users can use multiple recent checkouts of the development branch without
+needing to address the problem that some will print deprecation warnings and
+others do not, and also so that new deprecation warnings do not appear outside
+of the release period.
+<br>
+(Daniel Arndt, 2021/01/05)
diff --git a/include/deal.II/base/config.h.in b/include/deal.II/base/config.h.in
index fba8f32f69..1d46ca7b2c 100644
--- a/include/deal.II/base/config.h.in
+++ b/include/deal.II/base/config.h.in
@@ -149,7 +149,18 @@
 #cmakedefine DEAL_II_HAVE_CXX17_BESSEL_FUNCTIONS
 #cmakedefine DEAL_II_CXX14_CONSTEXPR_BUG
 
+/**
+ * Macro indicating that the current feature will be removed in a future
+ * release.
+ */
 #cmakedefine DEAL_II_DEPRECATED @DEAL_II_DEPRECATED@
+
+/**
+ * Same as above, but for things that have been deprecated during the current
+ * development cycle. By default, no warnings are printed for a feature
+ * deprecated prior to a release until <em>after</em> that release has been
+ * finalized - see DEAL_II_EARLY_DEPRECATIONS for more information.
+ */
 #cmakedefine DEAL_II_DEPRECATED_EARLY @DEAL_II_DEPRECATED_EARLY@
 #cmakedefine DEAL_II_FALLTHROUGH @DEAL_II_FALLTHROUGH@
 #cmakedefine DEAL_II_CONSTEXPR @DEAL_II_CONSTEXPR@