Document random($limit) behavior whe $limit has units (#664)

* document random($limit) behavior whe $limit has units

* add breaking change section for random-with-units

* add random-with-units link to sidenav

data/documentation.yml

@@ -60,6 +60,7 @@ toc:
  - <code>sass:string</code>: /documentation/modules/string
 - Breaking Changes: /documentation/breaking-changes
  :children:
+ - 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
  - <code>/</code> as Division: /documentation/breaking-changes/slash-div

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:
 
+* [`random()` with units](breaking-changes/random-with-units) beginning in Dart
+ Sass 1.54.5.
+
 * [Selectors with invalid combinators will be
  invalid](breaking-changes/bogus-combinators) beginning in Dart Sass 1.54.0.
 

source/documentation/breaking-changes/random-with-units.md.erb

@@ -0,0 +1,37 @@
+---
+title: "Breaking Change: Random With Units"
+introduction: >
+ The `random()` function will no longer ignore units on the `$limit` argument
+ in a future version. Passing a `$limit` with units is deprecated to ensure the
+ compilation results don't change once the new behavior lands.
+---
+
+[The `random()` function] has historically ignored units in `$limit` and
+returned a unitless value. For example `random(100px)` would drop "px" and
+return a value like `42`.
+
+A future implementation of Dart Sass will stop ignoring units for the `$limit`
+argument and return a random integer with the same units.
+
+[The `random()` function]: ../modules/math#random
+
+<% example(autogen_css: false) do %>
+ // Future Sass, doesn't work yet!
+ @debug math.random(100px); // 42px
+ ===
+ // Future Sass, doesn't work yet!
+ @debug math.random(100px) // 42px
+<% end %>
+
+## Transition Period
+
+<% impl_status dart: '1.54.5', libsass: false, ruby: false %>
+
+First, the Sass compiler will emit a deprecation warning for previous uses of
+`random()` when the `$limit` argument has units. The warning will suggest a way
+to preserve the existing behavior and another way that emulates the future
+implementation.
+
+In Dart 2.0.0 passing a `$limit` number with units will be an error, and then in
+a future minor release the `random()` function will return a random integer the
+same units as `$limit`.

source/documentation/modules/math.html.md.erb

@@ -540,6 +540,20 @@ title: sass:math
  If `$limit` is a number greater than or equal to 1, returns a random whole
  number between 1 and `$limit`.
 
+ <% heads_up do %>
+ `random()` ignores units in `$limit`. [This behavior is deprecated] and
+ `random($limit)` will return a random integer with the same units as the
+ `$limit` argument.
+
+ [This behavior is deprecated]: ../breaking-changes/random-with-units
+
+ <% example(autogen_css: false) do %>
+ @debug math.random(100px); // 42
+ ===
+ @debug math.random(100px) // 42
+ <% end %>
+ <% end %>
+
  <% example(autogen_css: false) do %>
  @debug math.random(10); // 4
  @debug math.random(10000); // 5373