From 5da5a38f0d26445003467ed0b7a046fb9c3ee82b Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Tue, 13 Jun 2017 22:21:50 -0700
Subject: [PATCH 1/2] Move scss functions from top of variables to separate
 file, then import it into other build files

---
 scss/_functions.scss       | 39 ++++++++++++++++++++++++++++++++
 scss/_variables.scss       | 46 --------------------------------------
 scss/bootstrap-grid.scss   |  1 +
 scss/bootstrap-reboot.scss |  1 +
 scss/bootstrap.scss        | 11 +--------
 5 files changed, 42 insertions(+), 56 deletions(-)
 create mode 100644 scss/_functions.scss

diff --git a/scss/_functions.scss b/scss/_functions.scss
new file mode 100644
index 000000000000..870df42a7931
--- /dev/null
+++ b/scss/_functions.scss
@@ -0,0 +1,39 @@
+@mixin _assert-ascending($map, $map-name) {
+  $prev-key: null;
+  $prev-num: null;
+  @each $key, $num in $map {
+    @if $prev-num == null {
+      // Do nothing
+    } @else if not comparable($prev-num, $num) {
+      @warn "Potentially invalid value for #{$map-name}: This map must be in ascending order, but key '#{$key}' has value #{$num} whose unit makes it incomparable to #{$prev-num}, the value of the previous key '#{$prev-key}' !";
+    } @else if $prev-num >= $num {
+      @warn "Invalid value for #{$map-name}: This map must be in ascending order, but key '#{$key}' has value #{$num} which isn't greater than #{$prev-num}, the value of the previous key '#{$prev-key}' !";
+    }
+    $prev-key: $key;
+    $prev-num: $num;
+  }
+}
+
+// Replace `$search` with `$replace` in `$string`
+// @author Hugo Giraudel
+// @param {String} $string - Initial string
+// @param {String} $search - Substring to replace
+// @param {String} $replace ('') - New value
+// @return {String} - Updated string
+@function str-replace($string, $search, $replace: "") {
+  $index: str-index($string, $search);
+
+  @if $index {
+    @return str-slice($string, 1, $index - 1) + $replace + str-replace(str-slice($string, $index + str-length($search)), $search, $replace);
+  }
+
+  @return $string;
+}
+
+@mixin _assert-starts-at-zero($map) {
+  $values: map-values($map);
+  $first-value: nth($values, 1);
+  @if $first-value != 0 {
+    @warn "First breakpoint in `$grid-breakpoints` must start at 0, but starts at #{$first-value}.";
+  }
+}
diff --git a/scss/_variables.scss b/scss/_variables.scss
index 5bd938c6b023..92d5e11e0a2c 100644
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -6,7 +6,6 @@
 // Variables should follow the `$component-state-property-size` formula for
 // consistent naming. Ex: $nav-link-disabled-color and $modal-content-box-shadow-xs.
 
-
 // Table of Contents
 //
 // Colors
@@ -44,51 +43,6 @@
 // Close
 // Code
 
-@mixin _assert-ascending($map, $map-name) {
-  $prev-key: null;
-  $prev-num: null;
-  @each $key, $num in $map {
-    @if $prev-num == null {
-      // Do nothing
-    } @else if not comparable($prev-num, $num) {
-      @warn "Potentially invalid value for #{$map-name}: This map must be in ascending order, but key '#{$key}' has value #{$num} whose unit makes it incomparable to #{$prev-num}, the value of the previous key '#{$prev-key}' !";
-    } @else if $prev-num >= $num {
-      @warn "Invalid value for #{$map-name}: This map must be in ascending order, but key '#{$key}' has value #{$num} which isn't greater than #{$prev-num}, the value of the previous key '#{$prev-key}' !";
-    }
-    $prev-key: $key;
-    $prev-num: $num;
-  }
-}
-
-// Replace `$search` with `$replace` in `$string`
-// @author Hugo Giraudel
-// @param {String} $string - Initial string
-// @param {String} $search - Substring to replace
-// @param {String} $replace ('') - New value
-// @return {String} - Updated string
-@function str-replace($string, $search, $replace: "") {
-  $index: str-index($string, $search);
-
-  @if $index {
-    @return str-slice($string, 1, $index - 1) + $replace + str-replace(str-slice($string, $index + str-length($search)), $search, $replace);
-  }
-
-  @return $string;
-}
-
-@mixin _assert-starts-at-zero($map) {
-  $values: map-values($map);
-  $first-value: nth($values, 1);
-  @if $first-value != 0 {
-    @warn "First breakpoint in `$grid-breakpoints` must start at 0, but starts at #{$first-value}.";
-  }
-}
-
-
-// General variable structure
-//
-// Variable format should follow the `$component-modifier-state-property` order.
-
 
 // Colors
 //
diff --git a/scss/bootstrap-grid.scss b/scss/bootstrap-grid.scss
index 2ba68587759b..722856c05cdb 100644
--- a/scss/bootstrap-grid.scss
+++ b/scss/bootstrap-grid.scss
@@ -23,6 +23,7 @@ html {
 }
 
 @import "custom";
+@import "functions";
 @import "variables";
 
 //
diff --git a/scss/bootstrap-reboot.scss b/scss/bootstrap-reboot.scss
index 5867f08ec98c..5965022a9966 100644
--- a/scss/bootstrap-reboot.scss
+++ b/scss/bootstrap-reboot.scss
@@ -3,6 +3,7 @@
 // Includes only Normalize and our custom Reboot reset.
 
 @import "custom";
+@import "functions";
 @import "variables";
 @import "mixins";
 
diff --git a/scss/bootstrap.scss b/scss/bootstrap.scss
index f7577f5c793b..239d062cf6bb 100644
--- a/scss/bootstrap.scss
+++ b/scss/bootstrap.scss
@@ -5,14 +5,11 @@
  * Licensed under MIT (https://github.com/twbs/bootstrap/blob/master/LICENSE)
  */
 
-// Core variables and mixins
 @import "custom";
+@import "functions";
 @import "variables";
 @import "mixins";
-
 @import "print";
-
-// Core CSS
 @import "reboot";
 @import "type";
 @import "images";
@@ -21,8 +18,6 @@
 @import "tables";
 @import "forms";
 @import "buttons";
-
-// Components
 @import "transitions";
 @import "dropdown";
 @import "button-group";
@@ -41,12 +36,8 @@
 @import "list-group";
 @import "responsive-embed";
 @import "close";
-
-// Components w/ JavaScript
 @import "modal";
 @import "tooltip";
 @import "popover";
 @import "carousel";
-
-// Utility classes
 @import "utilities";

From ac96ecbec5440b67f5c6c587e4c39d06b1262e34 Mon Sep 17 00:00:00 2001
From: Mark Otto <markd.otto@gmail.com>
Date: Tue, 13 Jun 2017 22:30:33 -0700
Subject: [PATCH 2/2] rearrange, add comments

---
 scss/_functions.scss | 26 ++++++++++++++++++--------
 1 file changed, 18 insertions(+), 8 deletions(-)

diff --git a/scss/_functions.scss b/scss/_functions.scss
index 870df42a7931..5aa9f6620933 100644
--- a/scss/_functions.scss
+++ b/scss/_functions.scss
@@ -1,3 +1,9 @@
+// Bootstrap functions
+//
+// Utility mixins and functions for evalutating source code across our variables, maps, and mixins.
+
+// Ascending
+// Used to evaluate Sass maps like our grid breakpoints.
 @mixin _assert-ascending($map, $map-name) {
   $prev-key: null;
   $prev-num: null;
@@ -14,7 +20,19 @@
   }
 }
 
+// Starts at zero
+// Another grid mixin that ensures the min-width of the lowest breakpoint starts at 0.
+@mixin _assert-starts-at-zero($map) {
+  $values: map-values($map);
+  $first-value: nth($values, 1);
+  @if $first-value != 0 {
+    @warn "First breakpoint in `$grid-breakpoints` must start at 0, but starts at #{$first-value}.";
+  }
+}
+
 // Replace `$search` with `$replace` in `$string`
+// Used on our SVG icon backgrounds for custom forms.
+//
 // @author Hugo Giraudel
 // @param {String} $string - Initial string
 // @param {String} $search - Substring to replace
@@ -29,11 +47,3 @@
 
   @return $string;
 }
-
-@mixin _assert-starts-at-zero($map) {
-  $values: map-values($map);
-  $first-value: nth($values, 1);
-  @if $first-value != 0 {
-    @warn "First breakpoint in `$grid-breakpoints` must start at 0, but starts at #{$first-value}.";
-  }
-}