Background
Summary
Because Codex is a shared library that must be maintainable, meet stringent accessibility/usability/design standards, and be understandable to users of the library, the burden of contributing is already high. Additionally, getting started with Codex development requires learning skills that aren't required for MediaWiki development, or at least haven't been required in the past (TypeScript, Vue 3/composition API, etc.) and learning a bespoke component documentation platform. We should consider how we can lower the burden for new contributors.
Impact
As a potential code contributor to Codex, I want to understand the various ways I could contribute code and what level of difficulty/time commitment is involved in each of those pathways.
As a new code contribute to Codex, I want to be able to make a satisfying and meaningful impact, without being bogged down by frustration
As a new code contributor to Codex, I want to be able to quickly contribute, without having to spend a large amount of time reading documentation or learning new technologies.
As a maintainer of Codex, I want to enable contributions from others, so we can benefit from their expertise and ideas and so that more work can be done on Codex than just the core maintainers could do on their own.
Lowering the burden of contributing code to Codex would have impact in several ways:
- Potential contributors will easily understand how they can contribute, whether that's a small patch with a simple fix or a new test, a new feature added to an existing component, or an entirely new component. Potential contributors with varying levels of time/availability and experience with technologies used within Codex will be able to find a way to meaningfully contribute.
- New contributors will be able to make a meaningful impact more quickly and with less frustration
- Codex maintainers will benefit from the work and ideas of people outside of the Design Systems Team
- More people will be familiar with and bought into Codex, increasing adoption and support for the project
- More work will get done on Codex, which will also lead to increased adoption and furthering the goals of the library at large (consistent UX and design, faster designer and developer velocity, wider use of modern technologies in the wikiverse, etc)
Proposed solutions
Removing demo requirements
Status: Complete – see T314792 and T311243
One requirement we could drop is the requirement of building component demos in VitePress. VitePress is not widely used and our setup is mostly custom, so it requires some explanation and will be new to all new contributors. Instead, we could allow demos to be created in separate tasks, and suggest that developers use the sandbox that comes with Vite in the Codex package.
This would require:
- Updating the contributing code docs to remove the requirement of VitePress demos and, instead, state that they can either be created during component development or separately by another developer.
- Clean up the sandbox, which is getting to be disorganized and unwieldy since it is a single file containing all components (see T311243)
Add section for experimental components
Status: Complete. See T313767
Another pathway we've considered in the past (see patch) is creating a separate entry for "experimental" components that aren't ready for wider use. We could set different requirements for components in this category and even forego testing them in CI.
Document the various pathways to code contribution
Status: Complete. See T313768
Currently, the contributing code docs contain an extensive list of patch requirements for new components. By implementing some of the other solutions above, we could revise this to explain that there are various ways to contribute code:
- The current process where the component, full set of demos, and full test coverage are completed
- An incremental process where the component, demos, and tests could be added separately (either by a single developer or multiple)
- A partnership process where a contributor could create the component or new feature, and partner with a DST member who will write tests and/or demos in related patches at the same time
- Probably more!
Support local development within Fresh environment
Status: To do. See T309899
Many MediaWiki developers use Fresh to run Node.js in a Docker environment for local development. We should ensure that this local dev pathway is supported and covered in our developer docs.
Implement VueUse for pre-made composition utilities
Status: To do. See T307089
VueUse is a library of composition utilities, or composables, that provide commonly needed functionality within Vue components. We currently write our own composables from scratch, but we could make component development easier and more standard by adopting VueUse and using the pre-made composables whenever possible. This would prevent developers from having to write the functionality themselves, and would make our work more standardized and therefore easier to onboard to.
Set clearer coding conventions
Status: To do. See T308520, T299242 , and T298667
There are a few areas where we could be more clear about the conventions we follow when we write code. Standardizing and documenting these conventions takes the guesswork out of local development, especially for a first-time Codex code author. We have 3 open tasks related to standards we need to determine and document:
- T308520: Standards around unit test naming and organization
- T299242: Conventions for custom event names
- T298667: Conventions for demo code
Set clear code review processes and guidelines
Status: Complete. See T313765
Code review can be a stressful, time-consuming, and confusing process. Let's make our processes very clear so contributors know what to expect, and set guidelines for healthy code review conduct to ensure that contributors are welcomed and encouraged.
Make the code review process easier through automation
Status: To do. See T313540
We already make use of things like linters to automatically catch common coding errors and issues. The more we can catch through these automated tools, the clearer the resolutions are to the code author, and the less time we have to spend discussion those issues during code review. Let's consider what else we can automate away.
Removing or changing unit test requirements
Status: Declined per discussion in DST engineering meeting 8/8/22 – unit test requirements should remain in place