This article describes how the enterprise wechat front end team uses Stylelint to do automated Code Review to improve CSS Code quality. The content includes from the technology selection at the beginning to the formulation of rules, and then how to effectively promote in the team and cooperate with SVN Hook to explore various automatic supervision mechanisms. The difficulty is how to deal with old project code and how to do effective member monitoring. It is hoped that the practice of enterprise wechat team can be used for reference by teams in CSS code quality anxiety.

The independent project of enterprise wechat project has been in a state of rapid iteration since the beginning. For the front-end team, the front-end development needs of enterprise wechat mainly focus on the two Web back-end management ends. In addition, there are multiple product versions (cloud version, private version, etc.) and several of their branches being developed in parallel. In terms of the composition of developers, it involves two regional development teams in Guangzhou and Chengdu. Since the first half of this year, we have gradually felt that the CSS Code is getting out of control due to the rapid iteration of the project and the current situation of insufficient time and manpower to support manual Code Review. From there, we had the idea to automate Code Review with lint and started doing it.

Technical selection: No surprises stylelint

Unlike JavaScript Lint tools that bloom in a thousand flowers, there are only three CSS Lint solutions available on the open source community: CSSLint, SCSS-Lint, and Stylelint. We naturally chose Stylelint for the following reasons:

  • Stylelint is based on PostCSS developed in pure JavaScript, and PostCSS is already well established in the team’s workflow. I have developed several PostCSS plug-ins, so the introduction is relatively smooth.

  • Stylelint extends CSS in a technical architecture based on AST. In addition to native CSS syntax, it also supports preprocessors such as SCSS and Less. In terms of community activity, there are a lot of third-party plugins.

  • Stylelint, a rising star of CSS Lint tools, has been put into practice in Facebook, Github, WordPress and other companies.

Drive plan: trilogy strategy

To help stylelint-based automated Code Review take root in team projects, we started with a three-step strategy: rule making, rule transition, and Rule automation.

1) Rule making period: in this stage, the enterprise wechat rule file will be customized first, and project team members will be required to install stylelint plug-in in editor or IDE to assist daily development. The specific stylelint rules can be discussed and adjusted according to the situation encountered during use.

2) Rule transition: this stage requires members to take time out of the development process to optimize the code of previous projects.

3) Rule automation supervision period: this stage will explore the establishment of the corresponding automatic supervision mechanism and implement it in daily development. In essence, there are two ways: one is to coordinate with SVN Webhook for real-time monitoring code reminder; the other is a monitoring report tool to display the daily generated code quality.

The plan of the “trilogy strategy” later turned out to be not strictly sequential in time. In the following sections, each phase is explained one by one.

Develop Stylelint rules

In the first phase of the “rule making period”, our first task is to develop Stylelint rules that belong to the enterprise wechat CSS development team.

Rules in a Stylelint Config come from the following three sources: Stylelint comes with rules, extends third-party rules, and writes plug-ins to customize rules.

Stylelint comes with more than 100 rules, which can be enabled and customized according to your personal situation. Font-size: 0px; Font-size: 0; . Using the rules that come with the stylelint length-zero-no-Unit fits our needs.

The actual running effect is as follows (run stylelint in terminal) :

Third-party rules are more likely to come from the open source community and are integrated into their own rule tables via plugins or extensions. If neither of the previous two approaches is possible, you can customize the rules by writing your own plug-in.

In the specification of enterprise wechat, we have several special needs that currently do not have relevant wheels in the community, for which we wrote a Stylelint plug-in to carry our needs.

For example, we require developers to add comments in the header of a new SCSS file, including key information such as filename, @data, @author, etc. To do this, we write a Stylelint rule called comments-in-header. If you are familiar with the development of the PostCSS plugin, it is easy to write out the related detection logic, along with the core detection code of the stylelint rule:

The actual running effect is as follows (in WebStorm) :

For example, in business SCSS files, CSS class names are strictly required to follow the SCSS file name (that is, the namespace is based on the SCSS file name). We also write a rule namespace-follow-filename for this purpose. In practice, there are files or code files in specific directories that do not follow this rule, so we have options for Stylelint’s Option API, which supports regular expressions.

It works like this (VS Code) :

For the custom rules generated in the enterprise wechat project, we have externally sorted out the stylelint-Weck-work-CSS plug-in to NPM and hosted the source code on Github (stylelint-Weck-work-CSS). If you are interested, You can hit star.

In addition, the Stylelint rule file used in our enterprise wechat project has been open source on Github, and you can refer to it if you are interested.

Problem: How can old code be modified

Phase one begins by asking team members to turn on the editor or IDE’s Stylelint plug-in as part of their daily development process to ensure that any new code generated is already linted. Then comes the second phase of the “rule transition,” where the big problem is what to do with the old code.

We didn’t choose to ignore the old code. During this “rule transition,” which has lasted until now, here’s what we did:

1) If the new requirement needs to be changed to the old file, the code of the file should be revised in accordance with the new rules.

2) Other documents can only be modified by extra time and manpower.

In terms of how to repair the old code, we also summarized a set of schemes as follows:

1) Take advantage of the fix function of the Stylelint

Stylelint Supports the — fix parameter to modify rules that can be fixed automatically. As with the length-zero-no-unit rule mentioned above, executing a command with the -fix parameter intelligently reduces the 0px in the target file. Zero without units;

2) Editor or IDE formatting code functions

Much of the old code did not conform to the indentation specification, missing corresponding Spaces and so on. This can be easily corrected to standard format code using an editor or IDE’s formatting function. We used WebStorm’s Code Formate function, which formats Code according to your stylelint rules. During this second phase of the “rule transition,” we found that this code format issue was dominating, and we also forced members to enable editorConfig.

3) Batch modification

Although there are no specific statistics, the above two items have actually solved about 80% of the revision workload. The rest need to be adept at using some of the IDE’s bulk replacement functionality to batch modify. As we did earlier for historical reasons, the sass code uses @mixin to handle browser prefixes. Many SCSS files still have these mixins after autoprefixer was added. For this purpose, we have developed a new stylelint rule unused-mixins, which can be easily replaced with webStorm’s batch regular replacements.

4) Use Stylelint Ignore well

Modifying old code is inherently risky. In the enterprise wechat CSS project, because the previous team members are still well controlled, so we have the confidence to repair most of the old code. But it is also true that there are parts of the code because of the legacy of the past bite or bite will affect the online business. In the actual situation of the project, there is also the need to avoid Stylelint detection. For example, the CSS code referenced by a third-party component needs to cover the relevant CSS styles. The code specification of the third-party component is different from the current project, but it is impossible to change the source code of the third-party component. At this point we need to handle with Stylelint Ignore.

The code above can be wrapped in stylelint-disable and stylelint-enable annotations to avoid stylelint detection. This feature is at risk of abuse to some extent, so we will require a reason to write this comment.

Establishment of automatic supervision system

From the beginning, it was our goal to establish a non-discriminatory, automated team discipline system with Stylelint as the technical core. If the system is to work, it needs to have a supervisory role. Otherwise, the project team can develop the stylelint plug-in as they please, and simply ignore the requirement to install the stylelint plug-in. Previously, we also considered the following two non-manual supervision schemes:

1) Add one more task to the current Sass compiled workflow, which will lint the changed files in real time, and directly remind you of errors and terminate compilation. Our current workflow is based on gulp and it is also easy to find the relevant gulp plug-in gulp-stylelint. But this is the fastest to reject, because it has an impact on Sass compilation speed and the “error warning and termination” approach is not very friendly.

2) Perform lint-related tasks before submitting code in hook mode. If an error occurs, the code will not be committed. Our project manages the code through SVN, and SVN Webhook on the server can be considered. Client hook is the same as requiring members to install the stylelint plug-in. If members are not enthusiastic, the same is useless.

The constraint (supervision) system should be at least semi-automated, and the third stage, “rule automation supervision period” came into being. We’ve done a lot of exploring, and these are the two that are currently in use.

1) Cooperate with SVN server Webhook for real-time monitoring and reminding

The internal SVN server of the company provides a Webhook interface. The author develops a simple Web server that can monitor the real-time stylelint code and remind it with the “post-commit” interface (the target path generates the hook triggered by SVN submission) and runs on the Intranet machine. The operation mechanism is shown as follows:

Whenever a project member commits code to the target path of the SVN server, webhook is automatically triggered, and the web server deployed on the Intranet resvn up these files somewhere and performs stylelint detection. If an error is detected, The detection result will be automatically sent to the member by email and enterprise wechat message to remind them to modify as soon as possible.

2) Daily report summary reminder

In addition, the author developed a simple report system with the help of Vue, which cooperated with crontab service to perform scheduled tasks. The functions are as follows: every day at 10:00 AM, SVN up the CSS code of the entire project and performs stylelint detection to generate archived reports on a daily basis and display them on a page accessible from the Intranet. The report page is accessible to all project team members, and the error information is clear at a glance. If the error code is not modified, it will remain on the page.

The report page is as follows:

Because the report information contains related information, such as SVN author, the system automatically sends an email or wechat message to remind related people. The actual effect is shown as follows:

The above two sets of supervision programs integrate the function of “display + reminder”. Since it is an automatic operation, daily supervision is equal to all project members. Of course, this oversight is only for reminders, so while it is automated, it still relies on human oversight when necessary, such as prodding people to maintain old code.

Summary and Future

Effect evaluation

We started to implement this automatic Code Review and supervision system based on Stylelint half a year ago, in order to improve the CSS Code quality of enterprise wechat project. In the past six months, although there is no specific quantitative data, it is generally effective. The results are as follows:

1) Effectively remedy the problems caused by human Code Review. In the past, projects mainly relied on manual Code Review, which required extra time to be arranged. In terms of cross-team cooperation, manual Code Review was often powerless. After the establishment of this system, the compliance of cross-team specifications is in a state of supervision, which partially liberates manpower and avoids possible disputes in manual Code Review.

2) The overall quality of the code is controllable. After the establishment of this system, the quality of the code generated every day can be seen, from the beginning of the warning correction, effectively avoid the accumulation of bad code more and more difficult to return to the situation. Because of the strict code format, the whole project code readable and maintainable naturally. So even if the enterprise wechat due to organizational changes and the adjustment of developers, the overall project code can be called in a controllable state.

3) Unexpected harvest: promoted the generation of CSS development documents of enterprise wechat. Up until this point, our development documentation had been written in a few pieces and scattered in a few places, and the rest was just word of mouth. This code quality improvement action directly prompted us to produce enterprise wechat UI development documents, including CSS specifications and development resources, etc.

Controversy, Outlook

Fully automated Code Review based on Stylelint is strictly desirable because it has limited functionality (for example, it is impossible to detect whether a CSS is better or worse). But in a development team, there are multiple people coming and going, with different levels of development, and the requirements are always coming and going. In terms of team operation, our pursuit is simple: to move forward in compliance with common specifications, better CSS capabilities depend on individual pursuit and manual Code Review.

On the other hand, engineers may prefer to let the machine do things like write 0px to 0 at the beginning of this article. 0px or 0 is essentially irrelevant to the project, and many developers prefer to use tools to handle these details later. However, we believe that only by focusing on the details can team members develop a sense of code specification as a whole and build “discipline” as a team. In Web development, there is no shortage of tools, but what is often lacking is a sense of self-rigor, self-code Review, and respect for teamwork. Tools are just a means, and a good developer can write code that meets the rules without the tools. There may be short-term pain in building these awareness, but we still think it’s worth it.

Looking to the future, in terms of CSS code quality of enterprise wechat project, in addition to the need to spend some time to maintain the old project code, we will develop more custom rules, continue to improve the current code specification, consolidate the current effective constraint system and explore more possibilities.