Document the bogus combinator breaking change (#654)

data/documentation.yml

@@ -60,6 +60,7 @@ toc:
   - <code>sass:string</code>: /documentation/modules/string
 - Breaking Changes: /documentation/breaking-changes
   :children:
+  - Invalid Combinators: /documentation/breaking-changes/bogus-combinators
   - <code>/</code> as Division: /documentation/breaking-changes/slash-div
   - Color Units: /documentation/breaking-changes/color-units
   - Extending Compound Selectors: /documentation/breaking-changes/extend-compound

source/documentation/breaking-changes.html.md.erb

@@ -23,6 +23,9 @@ time-sensitive, so they may be released with new minor version numbers instead.
 
 These breaking changes are coming soon or have recently been released:
 
+* [Selectors with invalid combinators will be
+  invalid](breaking-changes/bogus-combinators) beginning in Dart Sass 1.54.0.
+
 * [`/` is changing from a division operation to a list
   separator](breaking-changes/slash-div) beginning in Dart Sass 1.33.0.
 

source/documentation/breaking-changes/bogus-combinators.md.erb

@@ -0,0 +1,63 @@
+---
+title: "Breaking Change: Invalid Combinators"
+introduction: >
+  Sass has historically been very permissive about the use of leading, trailing,
+  and repeated combinators in selectors. These combinators are being deprecated
+  except where they're useful for nesting.
+---
+
+Sass has historically supported three invalid uses of combinators:
+
+* Leading combinators, as in `+ .error {color: red}`.
+
+* Trailing combinators, as in `.error + {color: red}`.
+
+* Repeated combiantors, as in `div > > .error {color: red}`.
+
+None of these are valid CSS, and all of them will cause browsers to ignore the
+style rule in question. Supporting them added a substantial amount of complexity
+to Sass's implementation, and made it particularly difficult to fix various bugs
+related to the `@extend` rule. As such, we [made the decision] to remove support
+for these uses.
+
+[made the decision]: https://github.com/sass/sass/issues/3340
+
+**There is one major exception**: leading and trailing combinators may still be
+used for nesting purposes. For example, the following is still very much
+supported:
+
+<% example do %>
+  .sidebar > {
+    .error {
+      color: red;
+    }
+  }
+  ===
+  .sidebar >
+    .error
+      color: red
+<% end %>
+
+Sass will only produce an error if a selector still has a leading or trailing
+combinator _after nesting is resolved_. Repeated combinators, on the other hand,
+will always be errors.
+
+To make sure existing stylesheets who (likely accidentally) contain invalid
+combinators, we'll support a transition period until the next major release of
+Dart Sass.
+
+## Transition Period
+
+<% impl_status dart: '1.54.0', libsass: false, ruby: false %>
+
+First, we'll emit deprecation warnings all double combinators, as well as
+leading or trailing combinators that end up in selectors after nesting is
+resolved.
+
+<%= partial '../snippets/silence-deprecations' %>
+
+In addition, we'll immediately start omitting selectors that we know to be
+invalid CSS from the compiled CSS, with one exception: we _won't_ omit selectors
+that begin with a leading combinator, since they may be used from a nested
+`@import` rule or `meta.load-css()` mixin. However, we don't encourage this
+pattern and will drop support for it in Dart Sass 2.0.0.

source/documentation/breaking-changes/slash-div.html.md.erb

@@ -57,6 +57,8 @@ To ease the transition, we've begun by adding the `math.div()` function. The `/`
 operator still does division for now, but it also prints a deprecation warning
 when it does so. Users should switch all division to use `math.div()` instead.
 
+<%= partial '../snippets/silence-deprecations' %>
+
 <% example(autogen_css: false) do %>
   @use "sass:math";
 

source/documentation/snippets/_silence-deprecations.erb

@@ -0,0 +1,9 @@
+<% fun_fact do %>
+  Remember, you can silence deprecation warnings from libraries you don't
+  control! If you're using the command-line interface you can pass the
+  [`--quiet-deps` flag], and if you're using the JavaScript API you can set the
+  [`quietDeps` option] to `true`.
+
+  [`--quiet-deps` flag]: /documentation/cli/dart-sass#quiet-deps
+  [`quietDeps` option]: /documentation/js-api/interfaces/StringOptionsWithoutImporter#quietDeps
+<% end %>