Document the moz-document breaking change on the sass website. (#667)

* Document the moz-document breaking change on the sass website.

Author: stof

data/documentation.yml

@@ -65,6 +65,7 @@ toc:
   - Media Queries Level 4: /documentation/breaking-changes/media-logic
   - <code>/</code> as Division: /documentation/breaking-changes/slash-div
   - Color Units: /documentation/breaking-changes/color-units
+  - <code>-moz-document</code>: /documentation/breaking-changes/moz-document
   - Extending Compound Selectors: /documentation/breaking-changes/extend-compound
   - CSS Variable Syntax: /documentation/breaking-changes/css-vars
 - Command Line: /documentation/cli

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

@@ -35,6 +35,9 @@ These breaking changes are coming soon or have recently been released:
 * [Color functions are becoming more strict about
   units](breaking-changes/color-units) beginning in Dart Sass 1.32.0.
 
+* [Parsing the special syntax of `@-moz-document` will be
+  invalid](breaking-changes/moz-document) beginning in Dart Sass 1.7.2.
+
 * [Compound selectors could not be extended](breaking-changes/extend-compound)
   in Dart Sass 1.0.0 and Ruby Sass 4.0.0.
 

source/documentation/breaking-changes/moz-document.md.erb

@@ -0,0 +1,38 @@
+---
+title: "Breaking Change: -moz-document"
+introduction: >
+  Firefox used to have a @-moz-document rule requiring special parsing. As
+  support is removed from Firefox, Sass is in the process of removing support
+  for parsing them.
+---
+
+Sass has historically supported a special parsing for the `@-moz-document` rule.
+As [Firefox dropped support for them], Sass will also drop support for the special
+parsing and will treat it as an unknown at-rule.
+
+[Firefox dropped support for them]: https://web.archive.org/web/20200528221656/https://www.fxsitecompat.dev/en-CA/docs/2018/moz-document-support-has-been-dropped-except-for-empty-url-prefix/
+
+
+**There is one exception**: an empty url prefix function is still allowed, as
+that's used in a hack targetting Firefox.
+
+<% example do %>
+  @-moz-document url-prefix() {
+    .error {
+      color: red;
+    }
+  }
+  ===
+  @-moz-document url-prefix()
+    .error
+      color: red
+<% end %>
+
+## Transition Period
+
+<% impl_status dart: '1.7.2', libsass: false, ruby: false %>
+
+First, we'll emit deprecation warnings for all usages of `@-moz-document`
+except for the empty url-prefix hack.
+
+In Dart Sass 2.0, `@-moz-document` will be treated as an unknown at-rule.