Code review

source/blog/041-import-is-deprecated.md → source/blog/043-import-is-deprecated.md

@@ -1,7 +1,7 @@
 ---
 title: "`@import` is Deprecated"
 author: Jennifer Thakar
-date: 2024-07-18 17:00:00 -8
+date: 2024-10-15 13:00:00 -8
 ---
 
 Back in 2019, we [released the Sass module system], adding new `@use` and
@@ -34,15 +34,15 @@ treat any Sass `@import` rules as errors.
 
 As previously announced, given the size of this change, we expect to wait at
 least a year after this deprecation before we remove `@import` from the
-language. While we expect Dart Sass 2.0.0 to be released soon with other,
-smaller breaking changes, that release will not include any changes to
-`@import`. Instead, we expect `@import` to be removed in Dart Sass 3.0.0.
+language. While we plan to release Dart Sass 2.0.0 soon with other, smaller
+breaking changes, that release will not include any changes to `@import`.
+Instead, we expect `@import` to be removed in Dart Sass 3.0.0.
 
 ## Migrator
 
-Users migrating off of `@import` can use the Sass migrator to move to the module
-system. Follow the [instructions] to install it, then run it
-on your application:
+Users migrating off of `@import` can use the Sass migrator to move to the
+module system. Follow the [instructions] to install it, then run it on your
+application:
 
 ```shellsession
 $ sass-migrator module --migrate-deps <path/to/style.scss>
@@ -53,9 +53,14 @@ $ sass-migrator module --migrate-deps <path/to/style.scss>
 ## Built-in Functions
 
 Alongside this deprecation, we are also deprecating any uses of global built-in
-Sass functions that are now available in built-in modules. The `global-builtin`
-ID can be passed to the `--silence-deprecation` or `--fatal-deprecation` flags
-on its own, or in combination with `import`. This deprecation will follow the
-same timeline as `@import` for removal. For users who want to migrate off of
-global functions but aren't ready to complete the module system migration,
-we've also added a new `--builtin-only` flag to the module system migrator.
+Sass functions that are now available in built-in modules. In the past, we've
+had a number of conflicts between these functions and new plain CSS function
+names, and moving to the module system will help us avoid further conflicts in
+the future.
+
+The `global-builtin` ID can be passed to the `--silence-deprecation` or
+`--fatal-deprecation` flags on its own, or in combination with `import`. This
+deprecation will follow the same timeline as `@import` for removal. For users
+who want to migrate off of global functions but aren't ready to complete the
+module system migration, we've also added a new `--built-in-only` flag to the
+module system migrator.

source/documentation/breaking-changes/import.md

@@ -3,8 +3,8 @@ title: 'Breaking Change: `@import` and global built-in functions'
 introduction: >
   Originally, Sass used `@import` rules to load other files with a single
   global namespace, with all built-in functions also available globally. We're
-  now deprecating both Sass `@import` rules and global built-in functions, now
-  that the module system (`@use` and `@forward` rules) has been available for
+  deprecating both Sass `@import` rules and global built-in functions now that
+  the module system (`@use` and `@forward` rules) has been available for
   several years.
 ---
 
@@ -14,25 +14,27 @@ manually namespaced to avoid conflicts, slowing down compilation when the same
 file is imported more than once, and making it very difficult for both humans
 and tools to tell where a given variable, mixin, or function comes from.
 
-The module system fixes these problems and brings Sass's modularity with the
-best practices of other modern languages, but we can't get the full benefits
-of it while `@import` remains in the language.
+The module system fixes these problems and brings Sass's modularity up to par
+with the best practices of other modern languages, but we can't get the full
+benefits of it while `@import` remains in the language.
 
-`@import` is now deprecated as of Dart Sass 1.78.0. Additionally, we're also deprecating the global versions of Sass built-in functions that are available
-in `sass:` modules
+`@import` is now deprecated as of Dart Sass 1.80.0. Additionally, we're also
+deprecating the global versions of Sass built-in functions that are available
+in `sass:` modules.
 
 ## Transition Period
 
-{% compatibility 'dart: "1.78.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
+{% compatibility 'dart: "1.80.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
 
 Sass `@import` rules and global built-in function calls now emit deprecation
-warnings. While we expect Dart Sass 2.0.0 to be released soon with various
-smaller breaking changes, we don't expect to remove Sass `@import` rules or
-global built-in functions until Dart Sass 3.0.0, which will be released no
-sooner than a year after Dart Sass 1.78.0.
+warnings. While Dart Sass 2.0.0 will be released soon with various smaller
+breaking changes, we don't expect to remove Sass `@import` rules or global
+built-in functions until Dart Sass 3.0.0, which will be released no sooner than
+a year after Dart Sass 1.80.0.
 
-Once Sass `@import` rules are removed from the language, all `@import` rules
-will be treated as [plain CSS `@import`s] instead. TODO: is this actually true?
+Eventually, all `@import` rules will be treated as [plain CSS `@import`s],
+likely after an intermediate period where anything that used to be a Sass
+`@import` throws an error.
 
 [plain CSS `@import`s]: /documentation/at-rules/import/#plain-css-imports