4 |
5 | `deprecate()` is a Sass mixin that helps managing code deprecation.
6 |
7 | 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.
8 |
9 | We (the Salesforce UX team) built this tool to help us [deprecate](https://en.wikipedia.org/wiki/Deprecation#Software_deprecation) code with confidence in the [Lightning Design System](https://www.lightningdesignsystem.com).
10 |
11 |
12 | ## Getting started
13 |
14 | Here is a typical workflow in which `deprecate()` comes in handy:
15 |
16 | ### v1.0.0
17 |
18 | Consider a Sass style guide in v1.0.0, button:
19 |
20 | ```scss
21 | $app-version: '1.0.0';
22 | @import 'path/to/deprecate/index.scss';
23 |
24 | .button { background: red; }
25 | ```
26 |
27 | ### v1.1.0
28 |
29 | We're introducing a new type of button, but we want to keep the old one in the code for backwards compatibility.
30 |
31 | ```scss
32 | $app-version: '1.1.0';
33 | @import 'path/to/deprecate/index.scss';
34 |
35 | @include deprecate('2.0.0', 'Use .button-new instead') {
36 | .button { background: red; }
37 | }
38 | .button-new { background: red; border: 3px solid blue; }
39 | ```
40 |
41 | ```css
42 | /* Compiled CSS */
43 | .button { background: red; }
44 | .button-new { background: red; border: 3px solid blue; }
45 | ```
46 |
47 | ### v2.0.0
48 |
49 | Major update: we don't want to ship deprecated code, and this is where Sass Deprecate comes into play:
50 |
51 | ```scss
52 | $app-version: '2.0.0';
53 | @import 'path/to/deprecate/index.scss';
54 | ...
55 | ```
56 |
57 | The compiler will start throwing warnings, such as:
58 |
59 | ```
60 | WARNING: Deprecated code was found, it should be removed before its release.
61 | REASON: Use .button-new instead
62 | on line 145 of index.scss
63 | from line 5 of button.scss
64 | ```
65 |
66 | And the compiled CSS won't include `.button`:
67 |
68 | ```css
69 | /* Compiled CSS */
70 | .button-new { background: red; border: 3px solid blue; }
71 | ```
72 |
73 | ## Advanced Semantic Versioning Support
74 |
75 | Need to compare version numbers such as `3.2.1-beta.5` and `1.2.3-alpha.2`?
76 |
77 | 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`).
78 |
79 | 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](https://github.com/KittyGiraudel/sass-semver):
80 |
81 | ```scss
82 | // Override the default SemVer resolution engine
83 | // with sass-semver: https://github.com/KittyGiraudel/sass-semver
84 | @import 'node_modules/sass-semver/index';
85 |
86 | @function deprecate-version-greater-than($version, $app-version) {
87 | @return gt($v1: $version, $v2: $app-version);
88 | }
89 |
90 | @import 'path-to/sass-deprecate/index';
91 | ```
92 |
93 | ## Running tests
94 |
95 | Clone the repository, then:
96 |
97 | ```
98 | npm install
99 | npm test
100 | ```
101 |
102 | ## Generating the documentation
103 |
104 | Sass Deprecate's API is documented using [SassDoc](http://sassdoc.com/).
105 |
106 | npm run generate-doc
107 |
108 | Generate & deploy the documentation to General
variables
app-version
$app-version: '1.0.0' !default;Description
Application version
Type
String
Used by
- [mixin]
deprecate
deprecate-mode
$deprecate-mode: 'sensible' !default;Description
Deprecation mode
Available modes:
disabled: output all the code, even if deprecatedsilent: disable all warnings but don't output deprecated codeverbose: show all warnings, even for code that is about to be deprecatedsensible(default): output warnings when deprecated code is detectedfail: prevent compilation when deprecated code is found
Type
String
Used by
- [mixin]
deprecate
mixins
deprecate
@mixin deprecate($version, $message) { ... }Description
Output code only until $app-version reaches $version and signal its deprecation to developers
Parameters
| parameterName | parameterDescription | parameterType | parameterDefault value |
|---|---|---|---|
$version | SemVer-like version (e.g. '2.0.0') | String | —none |
$message | Reason about why the code will be deprecated or possible workaround (e.g. 'Use .new-thing instead') | String | —none |
Requires
- [variable]
app-version - [variable]
deprecate-mode