Handling Renames and Deprecations

As we move existing CSS rules (ones that may be used by third-party code), we need to gracefully handle the transition so as not to break them.

For Less, any names being deprecated can remain the file, aliasing the old value and indicating the deprecation details.

// Deprecated as of Review Board 4.0.
@rb-my-component-bg-color: #rb-ns-my-component.colors[@bg];

// Mixins
.page-colors(@arg1, @arg2) {
    #rb-ns-page.mixins.page-colors(@arg1, @arg2);
}

// CSS rules
.some-old-rule {
    &:extend(.rb-c-new-rule all);
}

Sometimes &:extend doesn't work well enough, due to the use of something like .on-mobile-medium-screen-720(). In that case, just include the old version in the new definition and add a comment indicating it's deprecated:

.old-rule-name,  /* Deprecated */
.rb-c-new-rule {
    ...
}

It may also fail if using the &__<rule> form, in which case you'll nee to be explicit:

// This will fail.
.rb-c-foo {
    &__bar { ... }
}

.old-bar {
    &:extend(.rb-c-foo__bar);
}

// This will work.
.rb-c-foo { ... }
.rb-c-foo__bar { ... }

.old-bar {
    &:extend(.rb-c-foo__bar);
}

Elements that are simply transitioning to new CSS class names can retain the old names, allowing them to be overridden by other stylesheets.

<div class="rb-c-my-component my-old-component-name"></div>

Usually we will not want to bother with this, unless it's some really important element that we know will impact a big customer. Likewise, with the Less deprecations, we'll want to really only do this if we know these are being used in the wild somewhere.