Add `deprecate()` mixin (#28092)

scss/_mixins.scss

@@ -2,6 +2,9 @@
 //
 // Used in conjunction with global variables to enable certain theme features.
 
+// Deprecate
+@import "mixins/deprecate";
+
 // Utilities
 @import "mixins/breakpoints";
 @import "mixins/hover";

scss/_variables.scss

@@ -117,6 +117,7 @@ $enable-grid-classes:                         true !default;
 $enable-pointer-cursor-for-buttons:           true !default;
 $enable-print-styles:                         true !default;
 $enable-validation-icons:                     true !default;
+$enable-deprecation-messages:                 true !default;
 
 
 // Spacing

scss/mixins/_deprecate.scss

+// Deprecate mixin
+//
+// This mixin can be used to deprecate mixins or functions.
+// `$enable-deprecation-messages` is a global variable, `$ignore-warning` is a variable that can be passed to
+// some deprecated mixins to suppress the warning (for example if the mixin is still be used in the current version of Bootstrap)
+@mixin deprecate($name, $deprecate-version, $remove-version, $ignore-warning) {
+  @if ($enable-deprecation-messages != false and $ignore-warning != true) {
+    @warn "#{$name} has been deprecated as of #{$deprecate-version}. It will be removed entirely in #{$remove-version}.";
+  }
+}

scss/mixins/_text-hide.scss

@@ -7,7 +7,5 @@
   background-color: transparent;
   border: 0;
 
-  @if ($ignore-warning != true) {
-    @warn "The `text-hide()` mixin has been deprecated as of v4.1.0. It will be removed entirely in v5.";
-  }
+  @include deprecate("`text-hide()`", "v4.1.0", "v5", $ignore-warning);
 }

site/docs/4.2/getting-started/theming.md

@@ -243,6 +243,7 @@ You can find and customize these variables for key global options in Bootstrap's
 | `$enable-pointer-cursor-for-buttons`         | `true` (default) or `false`        | Add "hand" cursor to non-disabled button elements. |
 | `$enable-print-styles`                       | `true` (default) or `false`        | Enables styles for optimizing printing. |
 | `$enable-validation-icons`                   | `true` (default) or `false`        | Enables `background-image` icons within textual inputs and some custom forms for validation states. |
+| `$enable-deprecation-messages`               | `true` or `false` (default)        | Set to `true` to show warnings when using any of the deprecated mixins and functions that are planned to be removed in `v5`. |
 
 ## Color