Notes from MDN London meeting, September 2018.
Problems with current KumaScript
- Untested code that is used by thousands of pages
- No comments, documentation or specification for macros
- Too many macros
- Too much duplication of code
- Bad organization (“module” macros, lumped in data, l10n)
- L10n of text means editing code, which can lead to fall out
- No portability (e.g. compat table rendering outside of KS)
- A one line change in a “data macro” can cause fall out
- The repository has no clear maintainer, everyone maintaining it often means no one maintaining it (see the number of current open PRs)
- The KumaScript codebase is outdated, uses ejs and other aged node modules.
Decisions taken
Based on the problems outlined above and a discussion about the history of KumaScript, we then decided what we could do to address some of these problems. Here are some of the things will we do in the short term:
-
Broadly delete macros that are of little use.
- With fewer macros, everything should become easier:
- easier to write tests
- easier to reason about
- easier to refactor
- easier to replace them with better solutions.
- With fewer macros, everything should become easier:
-
Analyze KS landscape
- Classify macros to help us understand what we use macros for now, and make recommendations for what we should do with whole categories of macros.
-
Write and enforce policies for macros
- Once we’ve deleted many macros and analysed the landscape, it should become clear which kinds of macros we should keep. We will derive policies from these macros and make clear what we allow and disallow in KumaScript.
-
Testing is mandatory for code changes
- If you want to make code change to a macro, and the macro doesn’t have tests, then you should add basic tests in your PR. If it is a macro that is used on thousands of pages, this is most important.
-
De-macrofiy or delete inactive MDN content
- In London we’ve successfully removed all macros from the Archive and replaced them with their rendered version. This was done automatically using the PUT API (which is only available to MDN staff).
- We will continue de-macrofying other parts of MDN that are not Web docs and outdated (XUL, XPCOM, etc).
- We might delete content that is very out of date and not used by anyone anymore.
Work in progress
- Macro deletion spreadsheet. We’re working on broadly deleting useless macros. You’re welcome to help, however deleting macros can be tricky, so this requires some digging and deep understanding of the fragile KumaScript code base. Coordinate with @wbamberg and @fscholz before doing any work on this.
- As of the London meeting, we started with 432 macros we were quickly able to get down to 366 after the work week. See https://developer.mozilla.org/en-US/dashboards/macros for the current list of macros and their usage.
- Will and Florian are going to work on presenting a “KumaScript landscape” overview and will try to come up with a macro policy. Macro deletion can continue meanwhile.
KumaScript in 2019
- We will continue our short term cleanup efforts and then make a call sometime in 2019 if we should attempt to get rid of KumaScript altogether or try to modernize it for future use.
