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.
Here is a typical workflow in which deprecate()
comes in handy:
Consider a Sass style guide in v1.0.0, button:
$app-version: '1.0.0';
@import 'path/to/deprecate/index.scss';
.button { background: red; }
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; }
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; }
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 Hugo's sass-semver:
// Override the default SemVer resolution engine
// with sass-semver: https://github.com/HugoGiraudel/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';
Clone the repository, then:
npm install
npm test
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
- Taking Pattern Libraries To The Next Level, by Vitaly Friedman on Smashing Magazine
- Atomic Design, a book by Brad Frost
Thanks to Hugo Giraudel for his to-number
Sass function.