From 3cde41528145b3d616d95351b316bed9e0101102 Mon Sep 17 00:00:00 2001 From: Natalie Weizenbaum Date: Wed, 25 Sep 2019 14:24:50 +0100 Subject: [PATCH 1/3] Document the Sass migrator Closes #358 --- Rakefile | 22 ++ helpers/sass_helpers.rb | 1 + .../_example-module-migrator.html.md.erb | 25 ++ source/documentation/cli/migrator.html.md.erb | 289 +++++++++++++++++- 4 files changed, 336 insertions(+), 1 deletion(-) create mode 100644 source/code-snippets/_example-module-migrator.html.md.erb diff --git a/Rakefile b/Rakefile index 6f82747e1..d4c8917f2 100644 --- a/Rakefile +++ b/Rakefile @@ -67,6 +67,28 @@ namespace :sass do end end + namespace :migrator do + # Check out the latest commit of the Sass migrator into the .sass-migrator directory. + task :checkout do + unless Dir.exists?(".sass-migrator") + sh %{git clone git://github.com/sass/migrator .sass-migrator} + end + + Dir.chdir(".sass-migrator") do + sh %{git fetch} + if ENV["SASS_MIGRATOR_REVISION"] + sh %{git checkout #{ENV["SASS_MIGRATOR_REVISION"]}} + else + sh %{git checkout origin/master} + end + end + end + + task :version => :checkout do + add_version 'migrator', Dir.chdir(".sass-migrator") {latest_stable_tag} + end + end + namespace :libsass do # Check out the latest commit of Dart Sass into the .libsass directory. task :checkout do diff --git a/helpers/sass_helpers.rb b/helpers/sass_helpers.rb index 0f6536c6a..66ed06f99 100644 --- a/helpers/sass_helpers.rb +++ b/helpers/sass_helpers.rb @@ -322,6 +322,7 @@ def release_url(impl) repo = case impl when :dart; "dart-sass" + when :migrator; "migrator" when :libsass; "libsass" end diff --git a/source/code-snippets/_example-module-migrator.html.md.erb b/source/code-snippets/_example-module-migrator.html.md.erb new file mode 100644 index 000000000..02b7a5f84 --- /dev/null +++ b/source/code-snippets/_example-module-migrator.html.md.erb @@ -0,0 +1,25 @@ +```shellsession +$ cat style.scss +$body-bg: #000; +$body-color: #111; + +@import "bootstrap"; + +@include media-breakpoint-up(sm) { + .navbar { + display: block; + } +} +$ sass-migrator --migrate-deps module style.scss +$ cat style.scss +@use "bootstrap" with ( + $body-bg: #000, + $body-color: #111 +); + +@include bootstrap.media-breakpoint-up(sm) { + .navbar { + display: block; + } +} +``` diff --git a/source/documentation/cli/migrator.html.md.erb b/source/documentation/cli/migrator.html.md.erb index 1e429d1b3..c4f7fed31 100644 --- a/source/documentation/cli/migrator.html.md.erb +++ b/source/documentation/cli/migrator.html.md.erb @@ -1,5 +1,292 @@ --- title: "Migrator" +table_of_contents: true introduction: > - TODO(nweiz): Write this + The Sass migrator automatically updates your Sass files to help you move on to + the latest and greatest version of the language. Each of its commands migrates + a single feature, to give you as much control as possible over what you update + and when. --- + +## Usage + +To use the Sass migrator, tell it [which migration][] you want to run and what +Sass files you want to migrate: + +[which migration]: #migrations + +``` +sass-migrator +``` + +By default, the migrator will only change files that you explicitly pass on the +command line. Passing the [`--migrate-deps` option][] tells the migrator to also +change all the stylesheets that are loaded using the [`@use` rule][], +[`@forward` rule][], or [`@import` rule][]. And if you want to do a test run to +see what changes will be made without actually saving them, you can pass +[--dry-run][] [--verbose][] (or `-nv` for short). + +[`--migrate-deps` option]: #migrate-deps +[`@use` rule]: ../at-rules/use +[`@forward` rule]: ../at-rules/forward +[`@import` rule]: ../at-rules/import +[--dry-run]: #dry-run +[--verbose]: #verbose + +<%= partial 'code-snippets/example-module-migrator' %> + +## Installation + +You can install the Sass migrator from most of the same places that you can +install [Dart Sass](/dart-sass): + +### Standalone + +You can install the Sass migrator on Windows, Mac, or Linux by downloading the +package for your operating system [from GitHub][] and [adding it to your +`PATH`][]. + +[from GitHub]: <%= release_url(:migrator) %> +[adding it to your `PATH`]: https://katiek2.github.io/path-doc/ + +### npm + +If you use Node.js, you can also install the Sass migrator using [npm][] by +running + +[npm]: https://www.npmjs.com + +``` +npm install -g sass-migrator +``` + +### Chocolatey + +If you use [the Chocolatey package manager][] for Windows, you can install the +Sass migrator by running + +[the Chocolatey package manager]: https://chocolatey.org + +``` +choco install sass-migrator +``` + +### Homebrew + +If you use [the Homebrew package manager][] for Mac OS X, you can install Dart +Sass by running + +[the Homebrew package manager]: https://brew.sh + +``` +brew install sass/sass/migrator +``` + +## Global Options + +These options are available for all migrators. + +### `--migrate-deps` + +This option (abbreviated `-d`) tells the migrator to change not just the +stylesheets that are explicitly passed on the command line, but also any +stylesheets that they depend on using the [`@use` rule][], [`@forward` rule][], +or [`@import` rule][]. + +```shellsession +$ sass-migrator module --verbose style.scss +Migrating style.scss +$ sass-migrator module --verbose --migrate-deps style.scss +Migrating style.scss +Migrating _theme.scss +Migrating _fonts.scss +Migrating _grid.scss +``` + +### `--dry-run` + +This flag (abbreviated `-n`) tells the migrator not to save any changes to +disk. It instead prints the list of files that it would have changed. This is +commonly paired with the [`--verbose` option][] to print the contents of the +changes that would have been made as well. + +[`--verbose` option]: #verbose + +```shellsession +$ sass-migrator module --dry-run --migrate-deps style.scss +Dry run. Logging migrated files instead of overwriting... + +style.scss +_theme.scss +_fonts.scss +_grid.scss +``` + +#### `--no-unicode` + +This flag tells the Sass migrator only to emit ASCII characters to the terminal +as part of error messages. By default, or if `--unicode` is passed, the migrator +will emit non-ASCII characters for these messages. This flag does not affect the +CSS output. + +```shellsession +$ sass-migrator --no-unicode module style.scss +line 1, column 9 of style.scss: Error: Could not find Sass file at 'typography'. + , +1 | @import "typography"; + | ^^^^^^^^^^^^ + ' +Migration failed! +$ sass-migrator --unicode module style.scss +line 1, column 9 of style.scss: Error: Could not find Sass file at 'typography'. + ╷ +1 │ @import "typography"; + │ ^^^^^^^^^^^^ + ╵ +Migration failed! +``` + +### `--verbose` + +This flag (abbreviated `-v`) tells the migrator to print extra information to +the console. By default, it just prints the name of files that are changed, but +when combined with the [`--dry-run` option][] it also prints those files' new +contents. + +[`--dry-run` option]: #dry-run + +<%# Indent this because otherwise the table-of-contents generator interprets +the `===` as a heading. %> + + $ sass-migrator module --verbose --dry-run style.scss + Dry run. Logging migrated files instead of overwriting... + + style.scss + ================================================================================ + @use "bootstrap" with ( + $body-bg: #000, + $body-color: #111 + ); + + @include bootstrap.media-breakpoint-up(sm) { + .navbar { + display: block; + } + } + + -------------------------------------------------------------------------------- + $ sass-migrator module --verbose style.scss + Migrating style.scss + +## Migrations + +The migrator currently supports only one migration, but expect more to come as +the Sass language continues to evolve! + +### Module + +This migration converts stylesheets that use the old [`@import` rule][] to load +dependencies so that they use the Sass module system via the [`@use` rule][] +instead. It doesn't just naïvely change `@import`s to `@use`s—it updates +stylesheets intelligently so that they keep working the same way they did +before, including: + +* Adding namespaces to uses of members (variables, mixins, and functions) from + other modules. + +* Adding new `@use` rules to stylesheets that were using members without + importing them. + +* Converting overridden default variables to [`with` clauses][]. + + [`with` clauses]: ../at-rules/use#configuring-modules + +* Automatically removing `-` and `_` prefixes from members that are used from + other files (because otherwise they'd be considered [private][] and could only + be used in the module they're declared). + + [private]: ../at-rules/use#private-members + +* Converting [nested imports][] to use the [`meta.load-css()` mixin][] instead. + + [nested imports]: ../at-rules/import#nesting + [`meta.load-css()` mixin]: ../modules/meta#load-css + +<% heads_up do %> + Because the module migrator may need to modify both member definitions *and* + member names, it's important to either run it with the [`--migrate-deps` + option][] or ensure that you pass it all the stylesheets in your package or + application. + + [`--migrate-deps` option]: #migrate-deps +<% end %> + +<%= partial 'code-snippets/example-module-migrator' %> + +#### `--remove-prefix` + +This option (abbreviated `-p`) takes an identifier prefix to remove from the +beginning of all variable, mixin, and function names when they're migrated. +Members that don't start with this prefix will remain unchanged. + +The [`@import` rule][] put all top-level members in one global scope, so when it +was the standard way of loading stylesheets, everyone was incentivized to add +prefixes to all their member names to avoid accidentally redefining some other +stylesheet's. The module system solves this problem, so it's useful to +automatically strip those old prefixes now that they're unnecessary. + +```shellsession +$ cat style.scss +@import "theme"; + +@mixin app-inverted { + color: $app-bg-color; + background-color: $app-color; +} +$ sass-migrator --migrate-deps module --remove-prefix=app- style.scss +$ cat style.scss +@import "theme"; + +@mixin inverted { + color: theme.$bg-color; + background-color: theme.$color; +} +``` + +#### `--forward` + +This option tells the migrator which members to forward using the [`@forward` +rule][]. It supports the following settings: + +* `none` (the default) doesn't forward any members. + +* `all` forwards all members except those that started with `-` or `_` in the + original stylesheet, since that was commonly used to mark a package-private + member before the module system was introduced. + +* `prefixed` forwards only members that begin with the prefix passed to the + [`--remove-prefix` option][]. This option may only be used in conjunction with + the `--remove-prefix` option. + + [`--remove-prefix` option]: #remove-prefix + +All files that are passed explicitly on the command line will forward members +that are transitively loaded by those files using the `@import` rule. Files +loaded using the [`--migrate-deps` option][] will not forward any new members. +This option is particularly useful when migrating a Sass library, because it +ensures that users of that library will still be able to access all the members +it defines. + +```shellsession +$ cat _index.scss +@import "theme"; +@import "typography"; +@import "components"; +$ sass-migrator --migrate-deps module --forward=all style.scss +$ cat _index.scss +@forward "theme"; +@forward "typography"; +@forward "components/button"; +@forward "components/nav"; +@forward "components/drawer"; +``` From cdfa2039705da19400cbdcc00263c9dea855a713 Mon Sep 17 00:00:00 2001 From: Natalie Weizenbaum Date: Tue, 1 Oct 2019 14:43:21 -0700 Subject: [PATCH 2/3] Code review changes --- source/documentation/cli/migrator.html.md.erb | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/source/documentation/cli/migrator.html.md.erb b/source/documentation/cli/migrator.html.md.erb index c4f7fed31..bf95cf52d 100644 --- a/source/documentation/cli/migrator.html.md.erb +++ b/source/documentation/cli/migrator.html.md.erb @@ -253,6 +253,13 @@ $ cat style.scss } ``` +When you pass this option, the migrator will also generate an [import-only +stylesheet][] that [forwards][] all the members with the prefix added back, to +preserve backwards-compatibility for users who were importing the library. + +[import-only stylesheet]: ../at-rules/import#import-only-files +[forwards]: ../at-rule/forward + #### `--forward` This option tells the migrator which members to forward using the [`@forward` From 34cd9958931e7e0274d0f6fc9462d16593794617 Mon Sep 17 00:00:00 2001 From: Natalie Weizenbaum Date: Tue, 1 Oct 2019 14:57:25 -0700 Subject: [PATCH 3/3] Fix a broken link --- source/documentation/cli/migrator.html.md.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/documentation/cli/migrator.html.md.erb b/source/documentation/cli/migrator.html.md.erb index bf95cf52d..8682d3b03 100644 --- a/source/documentation/cli/migrator.html.md.erb +++ b/source/documentation/cli/migrator.html.md.erb @@ -258,7 +258,7 @@ stylesheet][] that [forwards][] all the members with the prefix added back, to preserve backwards-compatibility for users who were importing the library. [import-only stylesheet]: ../at-rules/import#import-only-files -[forwards]: ../at-rule/forward +[forwards]: ../at-rules/forward #### `--forward`