Extension:GrowthExperiments/Technical documentation/Coding conventions
The GrowthExperiments extension uses some coding conventions on top of MediaWiki's coding conventions manual.
Vue.js
[edit]These conventions are just for the GrowthExperiments client code. Please read first the MediaWiki Vue.js guide and Manual:Coding conventions/Vue for general considerations about writing Vue code in MediaWiki.
Limitations
[edit]All client JS code in the GrowthExperiments extension that uses Vue should use its version 3 and enable the compatibility mode compatConfig: { MODE: 3 }.
All client JS code in the GrowthExperiments extension that uses Vue should use SFC (Single File Components) with the extension .vue. See the known limitations of SFC loaded by ResourceLoader in Vue.js — Use single file components.
Naming
[edit]Ideally all components should have a name composed of two words, MyComponent. It's useful to use a domain concept on the first word (ie article, user, language) and a conventional web widget name (ie list, button, selector), for instance ArticleList, LanguageSelector, etc.
Low level components are intended to be reused by domain components and they are prefixed with a C (C stands for common or Codex). They do not enforce the restriction of two words since they usually represent a single user interface in a domain-agnostic way. Examples in the GrowthExperiments extension are CList, CListItem, CLink, CText. These components are candidates for an eventual upstream to Codex or a separated UI library.
Idioms
[edit]Ecmascript version
[edit]All client JS code written with Vue should be written in ES6. Please read about MWs ES6 limitations in Support for ES6 across MediaWiki. The usage of the spread operator ... in object and array literals is not supported.
Composition API
[edit]The GrowthExperiments extension started migrating code from OOUI to Vue when the supported Vue version was 2 and the Composition API was not yet released. Prefer using the Composition API versus the prior lifecycle and state APIs. The reason for this is to stay up to date with the latest Vue patterns and to facilitate an eventual upstream of the component to Codex or a separated UI library.
Render function vs <template>
[edit]Some components make use of Vue's render function while others use the <template> tag. It is Vue's conventional way to give full programmatic control over the rendering of a component. Prefer using templates as they ease the reading and understanding of a component's output due to its declarative nature. Use the render function only when needed.
Low level components
[edit]They represent the most basic widgets available to build more complex components. Similar to using a Codex or third party component. In order to facilitate its latter reuse there are some patterns enforced:
- Avoid using domain concepts such as article, user, edit, etc. and related business logic.
- Avoid making calls to MW/Vue i18n package. Any of these components displaying text should receive an already translated text string.
- Use the Composition API
Tests (WIP)
[edit]- Something about expectations for test coverage
- Something about snapshot tests, when to use, how to update the snapshots