openwebdocs
Automatization of linting in mdn/dom-examples (and more on mdn/content snippets)
Problem statement
In 2022, we set up some automatization of tools like MDlint on mdn/content. We also manually (or semi-manually) used Prettier and ESLint on code samples. In particular, we used them to improve our code during the modernization of JavaScript project.
The next step would be to systematically use Prettier and ESLint on code samples. Unfortunately, we are facing three major roadblocks:
- On HTML, the syntax used by Prettier may not be appropriate for beginners (especially the "slashes" on tags). We don't have a consensus about it, unlike JS and CSS snippets.
- mdn/content has snippets of code and not complete examples on pages. If this is not a problem for MDLint, and rarely one for Prettier, it makes the use of ESLint cumbersome, if not impossible.
- Synchronization between snippets and code examples in separate code repositories like mdn/dom-examples is fully manual: it means that any changes to mdn/content have to be back-ported to them (and reciprocally).
To have full automation of linting on MDN, we need to solve these three problems.
Proposed solutions
Solving all three problems and setting up full automation is out of reach for the moment. Without solving the whole shebang, we can make major progress in 2023, improving the coherence and quality of our examples.
Prettier
The absence of consensus on HTML linting should not block the use of Prettier on JS and CSS. PROPOSAL 1: I propose we work on automating the use of Prettier on CSS/JS snippets, excluding HTML and mixed snippets.
ESLint and code samples
Significant code examples are made using the following process:
- Write and test an independent code example.
- Store it in mdn/dom-examples (or in another repository)
- Extract and adapt code snippets from it, and incorporate them into mdn/content articles.
By automating the use of ESLint (and Prettier) in mdn/dom-examples (and in other code samples repositories), we ensure that most new code examples in mdn/content will also be linted (but indirectly).
This doesn't solve the entire problem but improves the situation on all new pages. PROPOSAL 2: Run ESLint on mdn/dom-examples (and other example repositories) and automate it.
Note: Two problems have been left aside:
- HTML linting, as we don't have a consensus yet with Prettier on HTML.
- Synchronisation between examples repositories and mdn/content that is a problem that is not mature enough to be tackled.
Task list
I propose to perform the following activities in 2023.
They are independent and can be performed in "sub-projects" in different Quarters, and not necessarily consecutively. Each one improves the state of MDN.
- [ ] Update mdn/dom-examples with Prettier (on JS and CSS) and automate it.
- [ ] Define ESLint rules and apply them on mdn/dom-examples, and automate it.
- [ ] Perform the same on other example directories.
- [ ] Update mdn/content code snippets with Prettier (on JS and CSS) and automate it.
Priority assessment
- Effort: This is a significant effort, it is a yearly project. But each element can be done independently during a Quarter (more or less). We can even stop or postpone it between each phases without losing the benefits of what is done.
- Dependencies: Give the work in 2022, none
- Community enablement: High. Modernization of JS in 2022 and automation of MDLint have shown that a team of volunteers gather and help a lot.
- Momentum: Medium to high. Volunteers that worked on automation in 2022 are still here or could still be reactivated.
- Enabling learners: Not directly. The discussion around which ESLint to activate is useful for learners (at least I learned a lot last year reading and driving them).
- Enabling professionals: Yes. Having high-quality examples allow professionals to reuse code more easily: they have less rewrite to do.
- Underrepresented topics / Ethical web: No.
- Operational necessities: Automation will need some review from devs. But this should stay marginal, as this will be similar to the automation we performed in 2022, and a good deal won't be on mdn/content, lowering the consequences in case of errors.
- Addressing needs of the web industry: Yes, modern examples are a must for the industry.
More information
For each phase, a specific, detailed, project roadmap will be created.
