From 3fe5591b4b00c90d003852a56d716b41d11f60ab Mon Sep 17 00:00:00 2001
From: Israel-4Ever <israel@idf.il>
Date: Thu, 15 Sep 2022 13:58:15 -0700
Subject: [PATCH] Document strict unary operators (#670)

---
 data/documentation.yml                        |  1 +
 .../breaking-changes/strict-unary.md.erb      | 64 +++++++++++++++++++
 2 files changed, 65 insertions(+)
 create mode 100644 source/documentation/breaking-changes/strict-unary.md.erb

diff --git a/data/documentation.yml b/data/documentation.yml
index a29258104..ffc8c58a1 100644
--- a/data/documentation.yml
+++ b/data/documentation.yml
@@ -60,6 +60,7 @@ toc:
   - <code>sass:string</code>: /documentation/modules/string
 - Breaking Changes: /documentation/breaking-changes
   :children:
+  - Strict Unary Operators: /documentation/breaking-changes/strict-unary
   - Random With Units: /documentation/breaking-changes/random-with-units
   - Invalid Combinators: /documentation/breaking-changes/bogus-combinators
   - Media Queries Level 4: /documentation/breaking-changes/media-logic
diff --git a/source/documentation/breaking-changes/strict-unary.md.erb b/source/documentation/breaking-changes/strict-unary.md.erb
new file mode 100644
index 000000000..d973284b7
--- /dev/null
+++ b/source/documentation/breaking-changes/strict-unary.md.erb
@@ -0,0 +1,64 @@
+---
+title: "Breaking Change: Strict Unary Operators"
+introduction: >
+  Sass has historically allowed `-` and `+` to be used in ways that make it
+  ambiguous whether the author intended them to be a binary or unary operator.
+  This confusing syntax is being deprecated.
+---
+
+How is this property compiled?
+
+<% example(autogen_css: false) do %>
+  $size: 10px;
+
+  div {
+    margin: 15px -$size;
+  }
+  ===
+  $size: 10px
+
+  div
+    margin: 15px -$size
+<% end %>
+
+Some users might say "the `-` is attached to `$size`, so it should be `margin:
+20px -10px`". Others might say "the `-` is between `20px` and `$size`, so it
+should be `margin: 5px`." Sass currently agrees with the latter opinion, but the
+real problem is that it's so confusing in the first place! This is a natural but
+unfortunate consequence of CSS's space-separated list syntax combined with
+Sass's arithmetic syntax.
+
+That's why we're moving to make this an error. In the future, if you want to use
+a binary `-` or `+` operator (that is, one that subtracts or adds two numbers),
+you'll need to put whitespace on both sides or on neither side:
+
+* Valid: `15px - $size`
+* Valid: `(15px)-$size`
+* Invalid: `15px -$size`
+
+If you want to use a unary `-` or `+` operator as part of a space-separated
+list, you'll (still) need to wrap it in parentheses:
+
+* Valid: `15px (-$size)`
+
+## Transition Period
+
+<% impl_status dart: '1.55.0', libsass: false, ruby: false %>
+
+We'll make this an error in Dart Sass 2.0.0, but until then it'll just emit a
+deprecation warning.
+
+<%= partial '../snippets/silence-deprecations' %>
+
+## Automatic Migration
+
+You can use [the Sass migrator] to automatically update your stylesheets to add
+a space after any `-` or `+` operators that need it, which will preserve the
+existing behavior of these stylesheets.
+
+[the Sass migrator]: https://github.com/sass/migrator#readme
+
+```shellsession
+$ npm install -g sass-migrator
+$ sass-migrator strict-unary **/*.scss
+```