Let Sass warn you about the pieces of your UI that are deprecated, providing a clear upgrade path for developers
Switch branches/tags
Nothing to show
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets Compile SassDoc May 16, 2016
sassdoc Compile SassDoc May 16, 2016
test Rename variable May 15, 2016
.editorconfig Add editorconfig Jan 18, 2016
.gitignore Ignore npm logs May 16, 2016
.sassdocrc Add sassdoc Jan 18, 2016
.travis.yml Test the build in all stable versions of Node May 15, 2016
CONTRIBUTING.md Update CONTRIBUTING.md Feb 16, 2017
LICENSE.txt Rename license to txt Feb 23, 2017
README.md Add "Mentioned in" section to the readme Mar 21, 2017
index.scss Update license to BSD 3-Clause Feb 23, 2017
package.json 1.1.3 Feb 23, 2017
sache.json Add to Sache Jan 19, 2016

README.md

Deprecate with confidence Build Status Greenkeeper badge

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 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';

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

Acknowledgments

Thanks to Hugo Giraudel for his to-number Sass function.