From 5f3180e7da036e4624851b144e1f1996b8399b85 Mon Sep 17 00:00:00 2001
From: Christophe Coevoet <stof@notk.org>
Date: Sat, 3 Sep 2022 02:47:21 +0200
Subject: [PATCH] Document the moz-document breaking change on the sass
 website.

---
 data/documentation.yml                        |  1 +
 .../breaking-changes.html.md.erb              |  3 ++
 .../breaking-changes/moz-document.md.erb      | 38 +++++++++++++++++++
 3 files changed, 42 insertions(+)
 create mode 100644 source/documentation/breaking-changes/moz-document.md.erb

diff --git a/data/documentation.yml b/data/documentation.yml
index d4f57a69b..a29258104 100644
--- a/data/documentation.yml
+++ b/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
diff --git a/source/documentation/breaking-changes.html.md.erb b/source/documentation/breaking-changes.html.md.erb
index 618669e65..10da4a7f7 100644
--- a/source/documentation/breaking-changes.html.md.erb
+++ b/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.
 
diff --git a/source/documentation/breaking-changes/moz-document.md.erb b/source/documentation/breaking-changes/moz-document.md.erb
new file mode 100644
index 000000000..d1835977f
--- /dev/null
+++ b/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 a 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.
+
+[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.