Background
Summary
We are on the cusp of wider use of the Codex library. In addition to documentation and infrastructure necessary for easy usage of any library, Codex has some oddities that will require some extra work to provide clear documentation and seamless usage of the library. In order to aid in adoption of Codex, we should consider how to make its use painless and easy.
Impact
As a developer user of Codex, I want to be able to quickly install the library and start effectively using components, icons, and design tokens.
As a developer user of Codex within MediaWiki, I want to be able to quickly install the library and start effectively using components, icons, and design tokens.
As a developer user of Codex within MediaWiki, I want to be able to easily test new releases or the main branch of Codex with my local MediaWiki instance.
As a MediaWiki designer, I want to be able to easily use Codex for my MediaWiki-specific designs.
Making it easier to use Codex would have impact in several ways:
- Increased and faster adoption of Codex and the current design system, leading to greater consistency for our users and faster deprecation of legacy libraries
- Increased buy-in to Codex, which may lead to more contributions to the library from people outside the Design Systems Team
- Increased developer velocity and satisfaction, which is one of the main goals of the library
- Potential use of Codex, which includes advanced accessibility, usability, and internationalization support, outside of the Wikiverse, leading to a more accessible internet
Proposed solutions
Use the latest release branch for the canonical live docs site
Status: To do, see T311097
Currently, the canonical live docs site is built on the main branch, which contains all merged work, including work which has not yet been part of a release. This has already caused confusion, because anyone working with the latest release in MediaWiki may see documentation on the site that does not yet apply with the version of Codex they're working with. We need to use the latest release branch, and change the canonical link to https://doc.wikimedia.org/codex/latest/ or something similar.
Document types and constants on the Codex docs site: ✓ done
Status: ✅ Done, see T300154
Currently, there is no way for a reader of the Codex docs site to get any information about types and constants that we use in the library. This is a major problem for components with props whose type is either a TypeScript type or a constant. The user sees the type or constant name, but has no way of getting information about the shape of those props. We must provide this information to the user if they're going to be able to effectively use that component.
Document component mixins
Status: To do, see T317160
We've decided to share some visual styles via Less mixins (like for links). We need to document these mixins on the docs site somehow so people know how to use them.
Add a class to the <html> element with the current Codex version
Status: To do, see T317162
We've already run into issues when making style changes in Codex that require simultaneous changes in an application that uses it. Add a class to the <html> element in MediaWiki with the current codex version would allow applications to write styles that target a specific version, helping to avoid collisions like this in the future.
Enable easier use of local Codex version for local MediaWiki development
Status: To do, see T314507
When doing local MediaWiki development, sometimes the developer will want to use a version of Codex other than the one provided in MediaWiki. For example:
- Testing a new release before updating
- Testing the main branch to gain access to unreleased work
Right now you can manually copy the built Codex library files into the proper place within MediaWiki core, but this is a pain, and we should provide an automated way to do this since it will be a commonly needed thing for MediaWiki developers. It's worth noting that this was a pain point with OOUI.
Document (and export) Codex composables
Status: To do, see T295186
We've written several reusable composition utility functions, some that pertain specifically to working in a MediaWiki context, that could be useful for Codex users, who will mostly be MediaWiki users. We should consider exporting them and documenting them on the docs site.
Avoid duplicate loading of Codex packages
Status: To do, see T310553
We created a special package, @wikimedia/codex-search, that contains TypeaheadSearch and its dependencies so that this package could be used within Vector to avoid including any unnecessary components there for the sake of performance. However, this means that if the entire @wikimedia/codex package is loaded on a page that also contains the Vector search bar, both libraries will be loaded, which means some code will be loaded twice. We should figure out how to avoid this.
Make README files NPM-appropriate
Status: To do, see T301730
Our README files are currently written in a way that refers to the whole of Codex, and not self-contained individual packages. This could be confusing when they're read in isolation, like on the NPM page for a package. We should rewrite these files to ensure that they're clear in any context.
Develop recommendations for how to set up unit tests
Status: To do, see T316415
Setting up unit tests for Vue components in MediaWiki skins and extensions is complicated. The ones that currently use Codex have more or less converged on a standard approach, but this approach is not well documented and could be improved. We should create clear guidelines for how to set up unit tests for Vue components in MW code, and how to deal with MW-specific and Codex-specific quirks.
Use same code style throughout repo and documentation
Status: Doing, see T320361
Ensuring that we use the same code style guidelines across the repo including Markdown documentation.
Help with code styling
We're currently relying only on ESLint/Stylelint.
We might want to ``use .editorconfig~~ (done ✓) and/or reconsider Prettier.
Enable documenting and document Stylelint configuration
Status: Doing, see T322710
With expanding Stylelint configuration it's important to share thinking behind it.
Provide non-TypeScript code examples
Status: To do, see T324375
It's important that the code examples in our documentation are easy to use for users who are not using TypeScript, which right now is almost all of them.