Testing And Avoiding Regressions.
Nevertheless, bugs and regressions can happen. Ideally, We want to avoid introducing issues and regressions in the codebase — conflicting styles, missing styles, incorrect markup, leaked styles from other elements, etc.
Using automated visual regression testing tools like Percy on a Pull Request level can speed up testing, allow developers to address regressions quickly and early, and make sure that the bugs don’t end up on the live site. These tools can take screenshots of individual pages and components and compare changes in style and layout and notify developers of any visual changes that can happen due to changes in the markup or CSS.
Since the CSS refactor process shouldn’t result in any visual changes in usual cases and depending on the task and issues in the legacy codebase, the visual regression testing process can potentially be simple as checking if any visual changes happened at all and checking if these changes were intentional or unintentional.
CSS is a simple stylesheet language for defining a website or document’s presentation.
However, this simplicity leaves the door open for many potential issues and technical debt — bloated code, specificity hell, duplicated code blocks with very little to no difference, leftover unused selectors, unnecessary hacks, and workarounds, to name a few.
Refactoring allows us to gradually and strategically make improves to our existing codebase, without changing its look and feel or core functionality. These improvements will (and should) be small in scope and limited, and will not introduce breaking, wide-ranging architectural changes or add new behavior, features, or functionality to the existing codebase.
Refactoring is a challenging process, yet much more complex than simply deleting the legacy code and replacing it with the refactored code. There is the matter of integrating the refactored codebase with the legacy codebase and avoiding regressions, accidental code deletions, preventing stylesheet conflicts. To avoid these issues, I would recommend using an incremental refactoring strategy.
One of the tools we used to analyze the codebase is CSS Stats. A free tool that provides a useful overview of the CSS codebase quality with lots of useful metrics that can help developers catch some hard-to-spot issues. Other tools are:
Yellow Lab Tools, is a free tool for auditing web performance, but it also includes some very helpful helpers for measure the complexity of your CSS — and also provides actionable insights into how to resolve these issues.
CSS Specificity Visualizer provides an overview of CSS selectors and their specificities across a CSS file. Once you submit a stylesheet, the tool returns a specificity graph.
Unlike other tools, Project Wallace, created by Bart Veneman, additionally keeps the history of your CSS over time. You can use webhooks to automatically analyze CSS on every push in your CI. The tool tracks the state of your CSS over time by looking into specific CSS-related metrics such as average selector per rule, maximum selectors per rule and declarations per rule, along with a general overview of CSS complexity.
The development team needs to make sure that the codebase health remains stable as long as they’re in charge of the codebase.
Technical debt which can result in potentially faulty CSS code should be isolated, documented, and implemented in a separate CSS file. Or added to the overrides.css.
Also obtaining a proper styleguide will help establish a standard way of writing CSS which means that code will always look and feel familiar to all members of the team.
Incremental (or granular) refactoring strategy.
To avoid conflicts with the legacy class names and to separate the refactored code from the legacy code more clearly, we’ll use an rf-
prefix on CSS class name selectors. Also overrides.css file will be created to add anything we need to override in the legacy CSS files. We also recommend updating a section of the override.css to include all the hacks we needed to do to get the refactored component to work.
Make sure to add useful comments in the overrides.css
file so other team members are on the same page and instantly know why the override has been applied and in response to which selector.
Visual regression testing can be treated as the last line of defense before merging the individual pull requests. Now rinse and repeat these three steps until the codebase has been refactored and overrides.css
is empty and can be safely removed.
When the codebase has been completely refactored and we’ve removed all makeshift TODO items from the overrides.css
file, we can safely remove it and we are left with the refactored and improved CSS codebase.
Create a new git branch for each task
With your first commit Create a PR(Pull Requests) for each branch
Point the PR from your branch to an integration branch
legacy-css__first-name]--[abbr. issue name]__issue[#number]
legacy-css__carolyn--sticky-submenu__issue571
This is the pattern library for the City of Boston.
CSS files are combined and minified to produce one giant final CSS file. There is also legacy css file that needs to be completely remove. The legacy/public.css
files needs to go. Create, move, and/or update the content into the main public.css
file. This should be achieved by moving the content into it's component .stylus
file. If the component does not exist but used on website, create a component for it on patterns. Clean out bos_
theme_
overrides.css
file on drupal. Simply remove all unnecessary styles from it.
Clean out all.js
on drupal and merge content into patterns all.js
The original functional specification for the City of Boston Website. Click here to download document.