## 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
### Document the various pathways to code contribution
Currently, the contributing code docs contain an extensive list of patch requirements for new components. By implementing some of the other solutions below, 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!
### Removing demo requirements
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)
### Removing or changing unit test requirements
Writing tests is another major burden during development. Removing the requirement for including unit tests is questionable because it prevents us from doing any form of TDD, and significant issues are often uncovered during the testing process. One way we could get around this is by allowing the author of patch to forego tests, but then pair them with a developer who will write the tests in a related patch at the same time. This way, tests are getting written during new component development, but the burden doesn't all fall on one person.
This would require:
- Ensuring that a coverage calculation lower than our threshold shows up in CI as a warning, not a blocking error
- Developing a process for this and documenting it
### Add section for experimental components
Another pathway we've considered in the past ([[ https://gerrit.wikimedia.org/r/c/design/codex/+/801816/2 | 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
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!
---
## Acceptance criteria
- [x] Discuss with the team what we want to do
- [x] Create subtasks
- [] Complete subtasks