One of the Design System’s principles is to include what’s shared and omit what’s not. To ensure the System provides the highest shared value to all product teams, contributions require an established need across three or more product teams to qualify for consideration.
When proposing a contribution, either small or large, identifying other teams with a shared need for the proposed feature or enhancement helps determine requirements and streamline the overall contribution process. The
#mds-engineering Slack channels are a great place to connect with other teams to gauge shared need.
Small changes that do not require a request for comment:
If a small change is really a large change, the System team may decline the change with a polite request to submit a Request for Comment first.
Many changes can occur through a pull request to the current release’s feature branch. This includes bug fixes and smaller documentation improvements that can be implemented and reviewed via the team’s normal pull request workflow. To learn about the System’s repository and how to use it or to coordinate design changes, send an email to firstname.lastname@example.org.
Changes that substantially impact the design, build, or tooling of the System require consensus among the System core team, segment owner, and contributor. Begin by proposing such changes via a Request for Comment. After receiving approval, submit a pull request as a next step.
Large changes can include:
The Request for Comment process protects the aspiring contributor from investing significant time to design, develop, and document a new feature that may not align with the System’s direction or vision.
To propose a feature via an RFC, email email@example.com, and include:
You may attach documents to your request, including diagrams, illustrations, designs, code snippets, or other relevant documentation.
Once an RFC is received, a System team member or the segment owner will review it. The System team and/or the segment owner will confirm that the contributor has sufficiently detailed the proposal and provide initial feedback. The triaging member may also solicit initial feedback from community members likely to have a strong opinion on the topic.
If further clarification or details are required, the contributor must submit a revised proposal after completing those changes.
After the initial review and revision process, the proposal will be open for discussion for a short period of time.
Within one to two weeks, the System team, segment owner, and contributor will collaborate to determine whether to approve the request. Collaboration can include email (for clarifications and more details), Slack discussion, and, if necessary, face-to-face meetings.
Usually, the group can reach a decision after a short period, based on discussion and threaded comments. On occasion, discussion may stall and relevant participants will need to make a decision.
Once approved to move forward, an RFC is considered “active” for implementation.
Activation is not a rubber stamp and does not mean the feature will ultimately be merged. It does mean that, in principle, all the major stakeholders have agreed to the feature and are amenable to incorporating it into the System.
Contributors may implement an active RFC, conforming to considerations of quality, consistency, and reuse relative to similar system concerns. Materials may include:
An RFC author need not be obligated to implement it, and may volunteer themselves or another contributor to complete the work.
Some RFCs represent vital features that need to be implemented right away. Other RFCs represent features that can wait until any arbitrary designer or engineer is available and interested in doing the work.
The System tracks active RFCs via a JIRA issue in the MDS project. This can include assignment to a specific contributor, including those outside the core team.
The RFC process was inspired by the Rust RFC documentation.