salesforce-ux/sass-deprecate

Let Sass warn you about the pieces of your UI that are deprecated, providing a clear upgrade path for developers

Deprecate with confidence

deprecate() is a Sass mixin that helps managing code deprecation.

How? Sass Deprecate warns about the pieces of your codebase that are deprecated, instructing developers where to clean up. It helps provide a clear upgrade path for framework and library users.

We (the Salesforce UX team) built this tool to help us deprecate code with confidence in the Lightning Design System.

Getting started

Here is a typical workflow in which deprecate() comes in handy:

v1.0.0

Consider a Sass style guide in v1.0.0, button:

$app-version: '1.0.0';
@import 'path/to/deprecate/index.scss';

.button { background: red; }

v1.1.0

We're introducing a new type of button, but we want to keep the old one in the code for backwards compatibility.

$app-version: '1.1.0';
@import 'path/to/deprecate/index.scss';

@include deprecate('2.0.0', 'Use .button-new instead') {
  .button { background: red; }
}
.button-new { background: red; border: 3px solid blue; }

/* Compiled CSS */
.button { background: red; }
.button-new { background: red; border: 3px solid blue; }

v2.0.0

Major update: we don't want to ship deprecated code, and this is where Sass Deprecate comes into play:

$app-version: '2.0.0';
@import 'path/to/deprecate/index.scss';
...

The compiler will start throwing warnings, such as:

WARNING: Deprecated code was found, it should be removed before its release.
REASON:  Use .button-new instead
	on line 145 of index.scss
	from line 5 of button.scss

And the compiled CSS won't include .button:

/* Compiled CSS */
.button-new { background: red; border: 3px solid blue; }

Advanced Semantic Versioning Support

Need to compare version numbers such as 3.2.1-beta.5 and 1.2.3-alpha.2?

By default, sass-deprecate only compares $version with $app-version in the form of Major.Minor.Patch (e.g. 1.2.3 with 2.0.0).

For advanced SemVer support in the form of Major.Minor.Patch-beta/alpha/rc.1, define a deprecate-version-greater-than($v1, $v2) function, or rely on Kitty's sass-semver:

// Override the default SemVer resolution engine
// with sass-semver: https://github.com/KittyGiraudel/sass-semver
@import 'node_modules/sass-semver/index';

@function deprecate-version-greater-than($version, $app-version) {
  @return gt($v1: $version, $v2: $app-version);
}

@import 'path-to/sass-deprecate/index';

Running tests

Clone the repository, then:

npm install
npm test

Generating the documentation

Sass Deprecate's API is documented using SassDoc.

npm run generate-doc

Generate & deploy the documentation to https://salesforce-ux.github.io/sass-deprecate/:

npm run deploy-doc

Mentioned in

• Taking Pattern Libraries To The Next Level, by Vitaly Friedman on Smashing Magazine
• Atomic Design, a book by Brad Frost

Acknowledgments

Thanks to Kitty Giraudel for their to-number Sass function.

sass-deprecate's Issues

Possible issue with fail deprecate mode.

Hello, cool project!
Looking to setup on our application.

Outline of my setup is below.
Figured I'd put the potential issue first.

There's a potential issue with the deprecate mode fail.
The following snippets are returned on different modes...

---

• Sensible

Running "sass:common" (sass) task
WARNING: Deprecated code was found, it should be removed before its release.
REASON:  Use .btn-primary-2-0-0 instead.
Backtrace:
    vendor/bower/sass-deprecate/index.scss:159, in mixin `deprecate`
    src/script/li/stylesheets/scss/_button.scss:59


Done, without errors.

---

• Verbose

Running "sass:common" (sass) task
WARNING: Some code will be deprecated in 2.0.0. Current version: 2.0.0.
Backtrace:
    vendor/bower/sass-deprecate/index.scss:119, in mixin `deprecate`
    src/script/li/stylesheets/scss/_button.scss:59

WARNING: Deprecated code was found, it should be removed before its release.
REASON:  Use .btn-primary-2-0-0 instead.
Backtrace:
    vendor/bower/sass-deprecate/index.scss:159, in mixin `deprecate`
    src/script/li/stylesheets/scss/_button.scss:59


Done, without errors.

---

• Fail

Running "sass:common" (sass) task
>> Error: Deprecated code was found. Remove it to continue.
>>        REASON:  Use .btn-primary-2-0-0 instead.
>>         on line 157 of vendor/bower/sass-deprecate/index.scss
>> >>           @error 'Deprecated code was found. Remove it to continue.#{$message}
>>    ----------^
Warning:  Use --force to continue.

Aborted due to warnings.

The output the Fail provides I would have expected to point to the offending code in the source of the project, not so much the sass-deprecation index, though I may be wrong here.

---

• My setup as outlined here

@import "base"; // importing vars for btn-primary
@import "index";

$app-version: '2.0.0';
$deprecate-mode: 'verbose';

$btn-primary-bg-2-0-0: #333;
$btn-primary-text-color-2-0-0: #ccc;
$btn-primary-border-color-2-0-0: #333;

@include deprecate('2.0.0', 'Use .btn-primary-2-0-0 instead.') {
  .btn-primary {
    @include button-type($btn-primary-bg, $btn-primary-text-color, $btn-primary-border-color);
    &:hover {
      color: $btn-primary-text-color;
    }
  }
}
.btn-primary-2-0-0 {
  @include button-type($btn-primary-bg-2-0-0, $btn-primary-text-color-2-0-0, $btn-primary-border-color-2-0-0);
  &:hover {
    color: $btn-primary-text-color;
  }
}

Write documentation

Write tests

Add a "message" parameter

Allows developers to communicate a reason for the deprecation or an upgrade/alternative path.

.foo {
  @include deprecate('0.1.2', $message: 'Use `.bar` instead') {}
}

Open source module

Steps before we open source this piece of code:

• Get approval
• Add CONTRIBUTING.md / contribution guidelines
• Add .editorconfig
• Add eyeglass entry point
• Add package.json / Publish on npm
• Add bower.json / Publish on Bower (bower install salesforce-ux/sass-deprecate should work)
• Add sache.json / Publish on Sache
• Add Salesforce_CLA.pdf

Questions about the “Getting started” section

Hello!

Lovely work on this; thanks for open-sourcing! I had a couple questions about the “Getting started” section in the readme:

1. Under v1.1.0 section, should $app-version: '1.0.0'; be $app-version: '1.1.0';?
2. As currently written, it seems to indicate (under the v2.0.0 section) that deprecations warnings won’t be thrown by the compiler until you ship 2.0.0. But wouldn’t those warnings start getting thrown in 1.1.0 in this example (since this is when you add the deprecation mixin around .button)?
3. Following up on the above and if I’m understanding correctly, in 2.0.0 you as a developer would completely remove .button and its styles? So at this point no deprecated code would be shipped (as indicated) and therefore these deprecation warnings also do not get shipped and they would not be output to the compiler in 2.0.0. Is this correct? Or do you continue to ship the .button selector wrapped in the deprecated mixin?

Thanks!

Externalize SemVer parsing

Hey, very nice library. I find the concept pretty cool and I admire the simplicity behind it. I can see how it would be useful for large projects moving fast (and trying not to break too many things).

I have been looking at the code and it’s stunning as always Kaelig, so I’ll make a single comment: I think the semver parsing and version comparison should not be part of sass-deprecate. The role of this library is to emit warnings and/or to remove code based on version numbers. Not to analyse and compare versions.

I would recommend you externalize the semver parsing and version comparison into another library, kind of like what npm does with https://github.com/npm/node-semver. Then, this library would be used as a dependency and expose a set of functions to compare versions, such as gt($version-a, $version-b) for instance.

There are a few benefits in doing this:

• It would remove about 80 lines of code from sass-deprecate if I’m right, which is basically dividing the amount of code per 2.
• It would make the semver parsing and version comparison more easily testable.
• It would make the semver parsing and version comparison re-usable in other projects needing it.
• It would be easy to replace this module with an actual node-semver binding through Sassport, or anything equivalent.
• Modular code is usually better.

Tell me if you want help with this.