# Next steps for KumaScript

**URL:** <https://discourse.mozilla.org/t/next-steps-for-kumascript/32227>\
**Category:** MDN\
**Created:** [October 1, 2018, 10:07am UTC](https://discourse.mozilla.org/t/next-steps-for-kumascript/32227 "2018-10-01T10:07:39Z")\
**Posts on this page:** 13\
**Page:** 1

<div class="post-metadata">

**Author:** ![fscholz](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/fscholz/32/25986_2.png) [@fscholz](https://discourse.mozilla.org/u/fscholz)\
**Post date:** [October 1, 2018, 10:07am UTC](https://discourse.mozilla.org/t/next-steps-for-kumascript/32227/1 "2018-10-01T10:07:39Z")

</div>

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.

- **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](https://docs.google.com/spreadsheets/d/1CaNZoKB3fx2tDMvJ_KTke4KS4KFpVBrHpdAisRVjbIk/edit#gid=0). 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](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.

---

<div class="post-metadata">

**Author:** ![exe-boss](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/exe-boss/32/43293_2.png) [@exe-boss](https://discourse.mozilla.org/u/exe-boss)\
**Post date:** [October 2, 2018, 11:02am UTC](https://discourse.mozilla.org/t/next-steps-for-kumascript/32227/2 "2018-10-02T11:02:27Z")

</div>

I’d like to point to my indicator style class simplification project, which I believe is relevant to this:

> [@Indicator style class simplification project: Prefer \`.blockIndicator\` for styling block indicators](https://discourse.mozilla.org/t/indicator-style-class-simplification-project-prefer-blockindicator-for-styling-block-indicators/31976):
>
> Indicators - in a perfect world each indicator is composed of 2 classes that combine to indicate how it should display. - one to indicate whether it is a block or a inline indicator - one to indicate what colour and icons it should halve - in practice there are multiple classes that indicate these things and a few indicators that only have one class to serve both purposes \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* Based on&nbsp;that, it&nbsp;seems like the&nbsp;CSS&nbsp;classes .…

> **[1492018 - Use a single class per indicator type](https://bugzilla.mozilla.org/show_bug.cgi?id=1492018)**
>
> RESOLVED (e7358d9c) in developer.mozilla.org Graveyard - General. Last updated 2020-05-15.

---

<div class="post-metadata">

**Author:** ![wbamberg](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/wbamberg/32/30597_2.png) [@wbamberg](https://discourse.mozilla.org/u/wbamberg)\
**Post date:** [October 26, 2018, 4:43pm UTC](https://discourse.mozilla.org/t/next-steps-for-kumascript/32227/3 "2018-10-26T16:43:04Z")

</div>

> Will and Florian are going to work on presenting a “KumaScript landscape” overview

This doc is here:

> **[KumaScript landscape](https://docs.google.com/document/d/1G5KwoJNi8mLmbzcWo-eawH0xw4spVvHGY4Wc4ZEuMYg/edit#heading=h.7vffxqvww614)**
>
> KumaScript landscape Introduction	2 Categorisation overview	2 Categories with a plan	4 Internal (88)	4 Xref (50)	4 Sidebar (35)	5 Compat (21)	6 Badges/Banners (43)	6 Data (4)	7 No-op (2)	7 Categories without a plan	8 Doc Status (10)	8 Embedding...

---

<div class="post-metadata">

**Author:** ![sheppy](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/sheppy/32/20903_2.png) [@sheppy](https://discourse.mozilla.org/u/sheppy)\
**Post date:** [October 26, 2018, 8:02pm UTC](https://discourse.mozilla.org/t/next-steps-for-kumascript/32227/4 "2018-10-26T20:02:26Z")

</div>

I have a number of thoughts on that plan, although generally it’s a good start. There are a couple of points where I strongly disagree, but I’m not at this very moment feeling coherent enough to write it all down adequately. 🙂

---

<div class="post-metadata">

**Author:** ![exe-boss](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/exe-boss/32/43293_2.png) [@exe-boss](https://discourse.mozilla.org/u/exe-boss)\
**Post date:** [October 26, 2018, 9:41pm UTC](https://discourse.mozilla.org/t/next-steps-for-kumascript/32227/5 "2018-10-26T21:41:43Z")

</div>

I’ve been putting together an experimental future syntax for replacing “One&nbsp;Page” macros at:  
[https://developer.mozilla.org/docs/User:ExE-Boss/KumaScript\_OnePage\_replacement#Syntax](https://developer.mozilla.org/docs/User:ExE-Boss/KumaScript_OnePage_replacement#Syntax)

---

<div class="post-metadata">

**Author:** ![sheppy](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/sheppy/32/20903_2.png) [@sheppy](https://discourse.mozilla.org/u/sheppy)\
**Post date:** [October 29, 2018, 3:10pm UTC](https://discourse.mozilla.org/t/next-steps-for-kumascript/32227/6 "2018-10-29T15:10:23Z")

</div>

> [@exe-boss](#):
>
> I’ve been putting together an experimental future syntax for replacing “One Page” macros at:

Hm. I guess I’m not picking up what the idea is here…

---

<div class="post-metadata">

**Author:** ![exe-boss](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/exe-boss/32/43293_2.png) [@exe-boss](https://discourse.mozilla.org/u/exe-boss)\
**Post date:** [October 29, 2018, 7:09pm UTC](https://discourse.mozilla.org/t/next-steps-for-kumascript/32227/7 "2018-10-29T19:09:59Z")

</div>

> [@sheppy](#):
>
> > [@exe-boss](#):
> >
> > I’ve been putting together an experimental future syntax for replacing “One Page” macros at:
> 
> Hm. I guess I’m not picking up what the idea is here…

The goal is to use a Liquid‑esque syntax for dynamic page generation using in‑page scripting syntax embedded inside the&nbsp;`{%`&nbsp;and&nbsp;`%}` delimiters.

Anyway, here’s a “test” page which shows how the&nbsp;[`WebExtAllCompatTables`](https://github.com/mdn/kumascript/blob/master/macros/WebExtAllCompatTables.ejs%60) macro could be&nbsp;replaced:  
[https://developer.mozilla.org/docs/User:ExE-Boss/KumaScript\_OnePage\_replacement/WebExtAllCompatTables](https://developer.mozilla.org/docs/User:ExE-Boss/KumaScript_OnePage_replacement/WebExtAllCompatTables)

Anyway, I’m still fleshing out the details of&nbsp;the&nbsp;syntax and which functionality we’d want to&nbsp;have.

---

<div class="post-metadata">

**Author:** ![sheppy](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/sheppy/32/20903_2.png) [@sheppy](https://discourse.mozilla.org/u/sheppy)\
**Post date:** [October 30, 2018, 9:24pm UTC](https://discourse.mozilla.org/t/next-steps-for-kumascript/32227/8 "2018-10-30T21:24:41Z")

</div>

The obvious problem with in-page scripting like that is the potential security and stability concerns. We would really need the ability to lock down pages to only be editable by trusted individuals or groups before we could use a capability like that.

---

<div class="post-metadata">

**Author:** ![exe-boss](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/exe-boss/32/43293_2.png) [@exe-boss](https://discourse.mozilla.org/u/exe-boss)\
**Post date:** [October 31, 2018, 1:04am UTC](https://discourse.mozilla.org/t/next-steps-for-kumascript/32227/9 "2018-10-31T01:04:20Z")

</div>

That and the principle of least power, which is why I want to use a Liquid‑like1 syntax, rather than full blown EJS, like the old `/docs/Template:` namespace.

* * *
**Footnote&nbsp;1** MediaWiki uses a similarly limited template syntax which anyone can use to&nbsp;create templates.

---

<div class="post-metadata">

**Author:** ![exe-boss](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/exe-boss/32/43293_2.png) [@exe-boss](https://discourse.mozilla.org/u/exe-boss)\
**Post date:** [November 5, 2018, 11:08pm UTC](https://discourse.mozilla.org/t/next-steps-for-kumascript/32227/10 "2018-11-05T23:08:54Z")

</div>

> [@wbamberg](#):
>
> > [@fscholz](#):
> >
> > Will and Florian are going to work on presenting a “KumaScript landscape” overview.
> 
> This doc is here:
> 
> [KumaScript landscape - Google Docs](https://docs.google.com/document/d/1G5KwoJNi8mLmbzcWo-eawH0xw4spVvHGY4Wc4ZEuMYg)

Can the sharing settings please be modified so that comments can be made directly on the document like in the macro massacre spreadsheet?

> **[KumaScript macro massacre](https://docs.google.com/spreadsheets/d/1CaNZoKB3fx2tDMvJ_KTke4KS4KFpVBrHpdAisRVjbIk/edit)**
>
> This Sheet is private

This way, I don’t have to post in this thread every time I need to comment on something.

---

<div class="post-metadata">

**Author:** ![wbamberg](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/wbamberg/32/30597_2.png) [@wbamberg](https://discourse.mozilla.org/u/wbamberg)\
**Post date:** [November 6, 2018, 9:57pm UTC](https://discourse.mozilla.org/t/next-steps-for-kumascript/32227/11 "2018-11-06T21:57:35Z")

</div>

I don’t really want to make the doc globally commentable. Can you comment in this thread?

---

<div class="post-metadata">

**Author:** ![exe-boss](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/exe-boss/32/43293_2.png) [@exe-boss](https://discourse.mozilla.org/u/exe-boss)\
**Post date:** [November 10, 2018, 1:57am UTC](https://discourse.mozilla.org/t/next-steps-for-kumascript/32227/12 "2018-11-10T01:57:43Z")

</div>

I have made some comments to the macros spreadsheet which I’d like to see addressed:

> **[KumaScript macro massacre](https://docs.google.com/spreadsheets/d/1CaNZoKB3fx2tDMvJ_KTke4KS4KFpVBrHpdAisRVjbIk/edit)**
>
> Macros
> 
> Macro Name, English Page Count, All Page Count, Used in other macros?, Category, Status, Decision/ Notes, Assignee, New all count, Diff
> NonStandardBadge, 4, 27, Yes, Badge/ Banner, compat, 27, 0
> deprecatedGeneric, 2, 63, Yes, Badge/...

---

<div class="post-metadata">

**Author:** ![exe-boss](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/exe-boss/32/43293_2.png) [@exe-boss](https://discourse.mozilla.org/u/exe-boss)\
**Post date:** [January 17, 2019, 12:40am UTC](https://discourse.mozilla.org/t/next-steps-for-kumascript/32227/13 "2019-01-17T00:40:30Z")

</div>

I’d like to&nbsp;be&nbsp;assigned to&nbsp;moving GroupData and&nbsp;InterfaceData to&nbsp;mdn‑data, as&nbsp;I’m&nbsp;doing this&nbsp;in:

> <https://github.com/mdn/data/pull/342>
>
> \*\*Edit:\*\* I&nbsp;completely forgot that @Google’s legal team still hasn’t approv…ed @jpmedley to&nbsp;contribute to&nbsp;this&nbsp;repository under the&nbsp;\*\*CC0\*\*&nbsp;licence, which frustrates me&nbsp;to&nbsp;no&nbsp;end (https://github.com/mdn/data/issues/240#issuecomment-418479029).
> 
> \---
> 
> This imports the&nbsp;\[\`GroupData.json\`\](https://github.com/mdn/kumascript/blob/e46969bb9d52526fdd25d063f4e52e533936fe7e/macros/GroupData.json) file from KumaScript (\<code\>inheritance&#x2011;data.json\</code\> is&nbsp;already up&nbsp;to&nbsp;date from&nbsp;\[\`InterfaceData.json\`\](https://github.com/mdn/kumascript/blob/e46969bb9d52526fdd25d063f4e52e533936fe7e/macros/InterfaceData.json)).
> 
> Part&nbsp;of&nbsp;https://github.com/mdn/sprints/issues/683, https://discourse.mozilla.org/t/next-steps-for-kumascript/32227 and&nbsp;https://discourse.mozilla.org/t/groupdata-and-macro-updates/32660
> 
> \---
> 
> review?(@chrisdavidmills, @davidflanagan, @Elchi3)

> <https://github.com/mdn/kumascript/pull/1041>
>
> This converts API&nbsp;macros to&nbsp;use \[mdn&#x2011;data\](https://github.com/m…dn/data) for&nbsp;data like what the&nbsp;CSS&nbsp;macros already&nbsp;do.
> 
> Part&nbsp;of&nbsp;https://github.com/mdn/sprints/issues/683 and&nbsp;https://discourse.mozilla.org/t/next-steps-for-kumascript/32227
> 
> \## Depends&nbsp;on:
> \- https://github.com/mdn/data/pull/342
> 
> \---
> 
> \*\*Tags:\*\* Macro&nbsp;massacre
> 
> review?(@wbamberg)