diff --git a/source/_data/documentation.yml b/source/_data/documentation.yml index e81815bad..a6d1bcbec 100644 --- a/source/_data/documentation.yml +++ b/source/_data/documentation.yml @@ -75,6 +75,7 @@ toc: - abs() Percentage: /documentation/breaking-changes/abs-percent/ - Functions and Mixins Beginning with --: /documentation/breaking-changes/css-function-mixin/ - Mixed Declarations: /documentation/breaking-changes/mixed-decls/ + - meta.feature-exists: /documentation/breaking-changes/feature-exists/ - Command Line: /documentation/cli/ :children: - Dart Sass: /documentation/cli/dart-sass/ diff --git a/source/documentation/breaking-changes/feature-exists.md b/source/documentation/breaking-changes/feature-exists.md new file mode 100644 index 000000000..e1231f993 --- /dev/null +++ b/source/documentation/breaking-changes/feature-exists.md @@ -0,0 +1,40 @@ +--- +title: 'Breaking Change: meta.feature-exists()' +introduction: > + The `meta.feature-exists()` function hasn't had any new features added in a + long time, and is now deprecated. Users should use other methods to determine + if a new feature is available. +--- + +Historically, Sass used the `meta.feature-exists()` function (also available as +the global `feature-exists()` function) to allow authors to detect whether +various new language features were available when compiling stylesheets. +However, as time has gone on it's turned out that the vast majority of new Sass +features are either possible to detect in a more straightforward way, or else +aren't very useful to detect at all. + +This function is now deprecated and will be removed in Dart Sass 2.0.0. Since +Dart Sass is now the only officially supported Sass implementation, and all +versions of Dart Sass support all the features supported by +`meta.feature-exists()`, all existing uses of it can safely be removed. + +Many new features can be detected using [`meta.function-exists()`], +[`meta.mixin-exists()`], or [`meta.global-variable-exists()`]. Others can be +detected using expression-level syntax, such as using `calc(1) == 1` to +determine if the current version of Sass supports first-class calculations. + +[`meta.function-exists()`]: /documentation/modules/meta#function-exists +[`meta.mixin-exists()`]: /documentation/modules/meta#mixin-exists +[`meta.variable-exists()`]: /documentation/modules/meta#variable-exists + +## Transition Period + +{% compatibility 'dart: "1.78.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %} + +First, we'll emit deprecation warnings for all usages of `feature-exists`. + +In Dart Sass 2.0.0, `meta.feature-exists()` will no longer exist. Attempts to +call it will throw an error, and attempts to call the global `feature-exists()` +function will be treated as a plain CSS function call. + +{% render 'silencing_deprecations' %} diff --git a/source/documentation/breaking-changes/index.md b/source/documentation/breaking-changes/index.md index 11d05ded2..0cd8b8509 100644 --- a/source/documentation/breaking-changes/index.md +++ b/source/documentation/breaking-changes/index.md @@ -22,6 +22,10 @@ time-sensitive, so they may be released with new minor version numbers instead. These breaking changes are coming soon or have recently been released: +* [The `meta.feature-exists()` function is + deprecated](/documentation/breaking-changes/feature-exists/) beginning in Dart + Sass 1.78.0. + * [Mixing declarations with nested rules is changing behavior](/documentation/breaking-changes/mixed-decls/) beginning in Dart Sass 1.77.7. diff --git a/source/documentation/modules/meta.md b/source/documentation/modules/meta.md index 857e415fa..c74286d80 100644 --- a/source/documentation/modules/meta.md +++ b/source/documentation/modules/meta.md @@ -241,6 +241,13 @@ title: sass:meta [interpolation]: /documentation/interpolation Returns `false` for any unrecognized `$feature`. + + {% headsUp %} + This function is deprecated and should be avoided. See [the breaking change + page] for details. + + [the breaking change page]: /documentation/breaking-changes/feature-exists + {% endheadsUp %} {% codeExample 'feature-exists' %} @use "sass:meta";