Retiring pieces of a design system
“Don’t break the build.”
The mantra you’ll hear often if you work with a continuously integrated product. Design systems, frameworks, pattern libraries or whatever we’re calling them this week usually live outside of the product(s) in which they’re used. They’re products in and of themselves, with their own team, their own backlog and their own release cycles. Updating to the latest version of your design system should rarely, if ever, intentionally break something which you previously supported.
Hell hath no fury like a developer who’s build breaks with a minor patch release of a dependency. Similarly, you’ll suffer scorn if you’re constantly releasing major versions because of the amount of breaking changes you’re publishing. The Pulsar design system got to version 6.x.x pretty quickly when we first started integrating it with our existing software products, but has stayed stable there for quite a while now because we’re increasingly focused on not breaking things. Which is generally a good thing for everyone.
Now, that’s not to say we don’t refactor things, or even remove things altogether, we do it all the time! We just take a few steps to make sure that the changes we make are as minimally disruptive as possible. The following process we use for retiring components may come in handy for you.
Retiring components
If you’re like us, you’ll have a lot of components with their related Sass files, every now and then we’ll go through ours and check they’re all still being used. After all, software features get retired and things get rewritten into newer and better alternatives so sometimes we need to just get rid of older components from the system.
Pulsar has a main Sass file pulsar.scss which imports all of the individual components but this is a reference file and not used in production. Each Continuum product has its own version of this file only importing the specific components they require, as well as adding any product-specific code they may need which aren’t appropriate to keep in Pulsar.
Say we want to remove a component no-one wants anymore, let’s call it _component.millhouse.scss, simply removing this file from the Pulsar repository would break the build of Continuum products attempting to import it.
!optional imports still aren’t a thing in Sass, unfortunately, so we take a few steps to gradually phase Millhouse out over a few releases.
1. Move the contents of _component.millhouse.scss into _deprecated.styles.scss
All Continuum products include this deprecated styles file, we include docblock-style comments to explain where they came from, why they’re being deprecated and the date which they were moved. This is useful for the later step of cleaning out the unwanted styles when we’re confident they’re no longer referenced in production.
/* -------------------------------------------------------------- *\04/07/2016 - Paul Stanton_component.millhouse.scssMillhouse component replaced by Nelson component.\* -------------------------------------------------------------- */.millhouse { ... }
At this point we’ve not broken the build, but our final CSS output still contains the .millhouse classes, we need to warn people that they’re being phased out.
2. Communicate the change
We publish release notes with each Pulsar version listing new features, bug fixes etc, and if we’re planning on removing something we mention it here too. But not everyone reads your meticulously crafted release notes so you can never guarantee someone will notice your warning.
Remember that empty _component.millhouse.scss file? Time to put it to use.
Sass has a handy @warn feature that lets you throw warning messages during compilation, we add a warning message inside this file informing product teams that the component is being phased out, and that this Sass file should be removed from their imports.
@warn '_component.millhouse.scss has been deprecated and needs to be removed from your main pulsar.scss file. UAT teams should not treat this as a build failure. (Stanton, 04/07/2016)'If you’re lucky enough to have dedicated test engineers, you’ll know that their finely tuned spidey-sense tingles whenever they sense a disturbance in the build, even though @warn will not trigger a build failure, it’s enough of an error to make them rightfully err on the side of caution and possibly fail a ticket. We include a message asking for it to not be treated as a build failure, but something that should still be followed up. Again, we put our name and date on the warning which helps the teams know who’s responsible for the warning and give them the chance to ping them on Slack, for example.
3. Remove the @import from the product
Each product team at Jadu has a Pulsar team member working within it, it’s usually us that will create a ticket and pull request to remove the reference to _component.millhouse.scss from the product’s mainpulsar.scss file. This then goes through the usual process of peer review and testing.
4. Remove the .millhouse code from _deprecated.styles.scss
After a while it should be safe to remove the .millhouse styles, normally we’d search the codebase for any remaining references of it in the products before we do, again, trying not to break the build, and typically we’d do this at the start of a sprint so that any unforseen regressions would hopefully surface during the course of regular work and testing.
We do visual regression testing on changes like this too, which helps to identify any unexpected consequences.
5. 🎉
Job done!
We’ve done this a few times in Pulsar to allow us to gradually and safely remove older code that may still be referenced in production, without the need to resort to releasing a new major version each time. If you have any better suggestions, we’d love to hear them!
