Document the deprecation of multiple variable flags (#716)

Closes #715
See sass/sass#2607

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

@@ -23,8 +23,8 @@ time-sensitive, so they may be released with new minor version numbers instead.
 
 These breaking changes are coming soon or have recently been released:
 
-* [Functions are stricter about which units they
-  allow](breaking-changes/function-units) beginning in Dart Sass 1.32.0.
+* [A variable may only have a single `!global` or `!default`
+  flag](breaking-changes/duplicate-var-flags) beginning in Dart Sass 1.62.0.
 
 * [Selectors with invalid combinators are
   invalid](breaking-changes/bogus-combinators) beginning in Dart Sass 1.54.0.
@@ -32,6 +32,9 @@ These breaking changes are coming soon or have recently been released:
 * [`/` is changing from a division operation to a list
   separator](breaking-changes/slash-div) beginning in Dart Sass 1.33.0.
 
+* [Functions are stricter about which units they
+  allow](breaking-changes/function-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.
 

source/documentation/breaking-changes/duplicate-var-flags.md.erb

@@ -0,0 +1,23 @@
+---
+title: "Breaking Change: Duplicate Variable Flags"
+introduction: >
+  Variables will only allow a single `!global` or `!default` flag. Duplicate
+  flags never had any additional effect, this just ensures that stylesheets are
+  more consistent.
+---
+
+## Phase 1
+
+<% impl_status dart: '2.0.0', libsass: false, ruby: false %>
+
+Starting in Dart Sass 2.0.0, if a single variable declaration has more than one
+each `!global` or `!default` flag, this will be a syntax error. This means that
+`$var: value !default !default` will be forbidden. `$var: value !global
+!default` will still be allowed.
+
+## Transition Period
+
+<% impl_status dart: '1.62.0', libsass: false, ruby: false %>
+
+Until Dart Sass 2.0.0 is released, multiple copies of a flag just produce
+deprecation warnings.

source/documentation/cli/dart-sass.html.md.erb

@@ -519,6 +519,11 @@ The following deprecation IDs can be passed to this option:
     <td>1.56.0</td>
     <td>Passing invalid units to built-in functions.</td>
   </tr>
+  <tr>
+    <td><a href="../breaking-changes/duplicate-var-flags"><code>duplicate-var-flags</code></a></td>
+    <td>1.62.0</td>
+    <td>Using multiple copies of <code>!global</code> or <code>!default</code> in a single variable declaration.</td>
+  </tr>
 </tbody>
 </table>