Macros and KumaScript

makro, greek, “large, big, wide”

Kuma, japanese, “bear”

Florian Scholz

Current status

• ~960 macros under the “Template:” namespace, written in node.js
• Editor on the wiki, stored as wiki pages.
• Migrated from MediaWiki -> DekiWiki -> Kuma (that’s a 10 year debt).
• Complexity and dependencies on (external) APIs (Kuma’s own “page API”, Bugzilla, BrowserCompat, …)
• Many unused macros
• Many macros doing outdated things.
• Some slow macros
• Specific single macros used on >10,000 pages.
• Macros are untested, not DRY, not documented.
• Macro editing requires additional privileges, but no review.
• No help available when working with them while editing wiki pages.

Macros gone wild

680

Florian Scholz

Scripts and modules macros

• Script macros: Create a link, create quicklinks navigation, ...
• Module macros: reusable functions for scripts.

​

• A lot of great things are produced by the script macros and make both editing and reading MDN a rich experience.
• What we need, though:
• A dry, documented, tested code base of macros that reflect the concepts of these macros
• A reviewed code base to minimize errors
• A code base that scales for usage on even more MDN pages.
• A better editing experience of macros.

The code that powers MDN content

Florian Scholz

Data and L10n macros

• Data macros. E.g. list of all CSS properties, inheritance data for APIs,...
• L10n macros. Translation dictionaries for scripts and for data.

​

• We are a provider of OPEN DATA ABOUT THE WEB
• This data should be editable by us like now in these macros.
• We should make this data available for other consumers outside of KumaScript.

Providing json data

Florian Scholz

GitHub

• Idea: Move macro code to GitHub.
• https://github.com/mozilla/kumascript/
• macros/
• data/
• l10n/
• modules/
• scripts/
• quicklinks/
• cssreference/
• browsercompat/
• tests/

… to the rescue?

Florian Scholz

GitHub

• PR == everyone can contribute with GitHub account and we finally review macro code and make it pretty rather than quick.
• You can edit macros in the editor of your choice.
• A testsuite/CI is TBD but I think is doable as KumaScript macros basically create strings and call some APIs here and there.
• A clearer folder structure lets us find and maintain macros more easily.
• What we actually do with macros becomes more clear! If we think we shouldn’t be doing this at all in KumaScript, but on the platform level, we have the stuff together and the concepts are much more readable.

… to the rescue?

Florian Scholz

GitHub

• Future (v2): The data and l10n folders might be a special case:
• It is JSON
• We probably want a nice interface to edit this data.
• Pontoon or other tools for l10n jsons?
• Make this data available as MDN’s Open Data API for real somehow. data.developer.mozilla.org.

​

• Performance
• Macros get deployed, minified and cached somewhere.
• Not loaded from the DB anymore.
• [I am not technical enough to say more about perf here]

… to the rescue?

Florian Scholz

How to get there?

• Let’s not migrate all the crap over to GitHub.
• Let’s have a transition phase where we have macros loaded from the wiki like now, and macros loaded from the new world, but well tested etc.
• Let’s remove all the macros that we don’t need anymore on our way.

​

​

• (Yes, in theory, a wiki should be revertable to any point in history, but to be honest: This is very unlikely, and even with the current environment it will be very hard. I propose to get rid of what we don’t need anymore. deleted=1 flag it is anyway, I assume.)

​

Transition phase

Florian Scholz

Open questions

• Governance: Who will review the PRs?
• How often can we expect deploys? (Data macros get changed often)
• How can we test the PRs before deployment? (currently we just code something and then see if it works, resulting in many wiki edits on the macros)

​

?!

Florian Scholz

Thanks!

Email: fscholz@mozilla.com

​

Please feel free to comment these slides, too.

Please contact me for feedback

Florian Scholz