Design System Team/Team Processes

Continuous improvement is better than delayed perfection.
—Mark Twain

Scrum Principles

Design System Team (DST) uses the Scrum framework,^[1] which includes:

Sprints: time-boxed product development increments. DST works in two-week sprints, each of which includes specific events to plan and break down work, reflect on team health and process improvements, share what we have learned, and change our future plans if needed.
Visual representation of project tasks: using Phabricator, DST makes upcoming and in-progress work visible to the world, and allows team members autonomy to "pull" prioritized work through stages of design and development.
Daily stand-up: an asynchronous update to inform each other what we did yesterday, what we're focusing on today, and highlight blockers/dependencies.
Estimation: the team provides an estimated point value of each task, accounting for scope, complexity, and unknowns, allowing shared understanding of acceptance criteria and expected completion.

Estimation

Task creator describes the task at a high level. Team has a chance to discuss/clarify/refine.
Engineers select the number that correlates to their estimate of the task. Currently, the team is piloting a model where 1 point = 1 day. Critically, this is not just time, but complexity - think of this as not “time at keyboard”, but “time at keyboard” + “time to coordinate with other teams” / “time to research solutions” / “amount of complexity of task” / "back and forth of code review".
Estimates may be updated at any time as the work progresses.
For bug and spike tasks, a timebox estimate is preferred. Instead of asking "how much time will this roughly take?", we should be asking "how much time do we want to spend on this?". This should ideally be 1-2 points at most, with the understanding that after the estimate has "expired", the assignee is expected to report back to the team with their findings.
For bugs specifically, the timebox estimate is intended to represent the "investigation" period of understanding a bug (setting up the right test environment, testing, determining the root cause), and not necessarily fixing the bug. This is intended to create an opportunity to evaluate solutions of varying scope and scale, including not needing to address the issue at all, thus avoiding scope creep of what might seem like a "simple fix".

DST Phabricator Norms

For general Phabricator documentation, see: https://www.mediawiki.org/wiki/Phabricator

Phabricator Task Prioritization

Priority levels signal to ourselves and the world: How important is this task? When do we expect to complete this task?

Unbreak Now! (UBN) = Something is broken and needs to be fixed immediately, setting anything else aside. This should meet the requirements for issues that hold the train. UBN issues are examples of tasks that may get pulled in mid-sprint.
High = These tasks are critical for accomplishing our near-term goals. For tasks in the sprint, these represent tasks that we will drop other work for to complete. For tasks in "Up Next", these represent tasks that should be brought into the next sprint, if possible.
Medium = Tasks that are relevant to our near-term goals, but which can be deferred if capacity is needed to tackle UBN or high priority tasks.
Low = Tasks we would like to get around to but are not directly relevant to near-term goals. Low priority tasks—especially small ones—can and should still be considered during sprint planning when extra capacity is available.

Phabricator Boards

Design-System-Product-Roadmap

General guidance:

Goal is a high-level view of our roadmap.
Contains only epic- and key result-level tasks.

COLUMN NAMES	DESCRIPTION
Supporting	Larger efforts from other WMF teams or technical volunteers we are supporting, but not actively driving.
Now (Default)	Contains epics we are actively working on now.
Next	Contains epics we want to focus on next. These may be in early research/discovery.
Later	Contains epics we want to prioritize later in the year. This column is NOT an "icebox" or catch-all for ideas; rather, we intend to work on these epics as part of our annual plan and/or team goals.
Parking Lot	Contains epics we are explicitly not working on and do not have plans to work on, but are still relevant and may be prioritized at some point in the future.

Design-System-Team

General guidance:

Design-System-Team is our main “home” in Phabricator. It contains Design-System-Sprint-# milestone boards within it.

COLUMN NAMES	DESCRIPTION
Inbox (Default)	All new tasks tagged with Design-System-Team land here by default. Requests from teams/contributors outside DST should be reviewed within one week and next steps communicated in the task. DST members should create tasks directly in the backlog or other appropriate column instead of the Inbox.
Triaging	Tasks from the Inboxed are moved into this column when additional information, discussion, or investigation is needed before a triage decision can be made. Not all tasks from the Inbox will need to move into this column.
Backlog	Contains tasks we want to complete at some point in the future, but does not align with near-term goals or plans.
Needs Refinement	Contains tasks that have been prioritized but have not been refined or estimated and are NOT ready to pick up.
Up Next	Tasks in this column are ready to pick up and are evaluated during Sprint Planning to be pulled into a sprint. All tasks in this column are prioritized, refined, and have an estimate.
DST-Sprint-#	This is a milestone column - when clicked, it opens up the Design-System-Sprint-# board. Tasks cannot live on both Design-System-Team and Design-System-Sprint-#. See below for more guidance.
Following	Contains tasks we are interested in, but not actively working on. These could be tasks owned by other teams or our own tasks that we are awaiting feedback on.

DST-Sprint-#

General guidance:

Contains tasks we are working on right now.
A new board is created every two weeks, and the previous board is archived.
Tasks typically move from left to right as they progress through our workflow.
Individual team members should work from right to left: first unblock pending reviews, then finish tasks in progress, then pick up new tasks.
Tasks on this board can span design, product, and engineering work.
All tasks on this board should have a priority level.
All engineering tasks on this board should have an estimate.
Tasks scheduled for deployment on the train should get tagged with the version number e.g. MW-1.37-notes (1.37.0-wmf.14; 2021-07-12) .
If you need a code or design review, please highlight this in your daily standup within the #design-system-private Slack channel.
Generally, Phabricator tasks should go through triage & refinement in Design-System-Team. However, sometimes tasks need immediate action - feel free to move these items into the current Design-System-Team sprint and let the team know in your standup.

COLUMN NAMES	DESCRIPTION	Who moves tasks IN?	Who moves tasks OUT?	Assignee?
Committed (Default)	Contains tasks that have been refined, prioritized, and are ready to be worked on.	PM, Engineering, Design	Assignee	Anyone may claim these tasks to begin work.
Blocked	Contains blocked tasks.	Anyone on DST	Anyone on DST	The person shepherding the unblocking of the task.
In Progress	Contains tasks actively being worked on, regardless of task type (i.e. regular task, spike, bug fix).	Engineering	Engineering	Engineer
Design Review	Contains tasks in design review.	Engineering	Engineering	Leave assigned to original engineer.
Code Review	Contains tasks in code review.	Engineering	Engineering	Leave assigned to original engineer.
Pending Release	Contains completed tasks; after release the task is closed*.	Whoever signed off on the task	Developer who completed the release

*Only tasks with work that will be part of the next Codex release should go into Pending Release. Tasks that are not part of the actual release, like design deliverables or process-related items, can be set as "Resolved" when they are completed.

Guidance for "running out of work" in the current sprint:

This shouldn’t happen often! If we've done adequate refinement & capacity planning then this should be rare, but of course, it can and does happen.
Consider other things before we discuss pulling in new work: are there tasks in code review or in progress we can swarm on/pair to finish? Prioritize closing out sprint goals. A "meta-goal" of every sprint is to close out all the task we've committed to.
Avoid individual team members pulling things into the sprint automatically: if there are no tasks on sprint board to help with, default to a team conversation. Post back to the team Slack channel highlighting the additional capacity and tag the PM to make sure everyone is on same page.
If needed: the team may schedule an ad hoc refinement/planning session to discuss what the upcoming priorities are. This can happen in Slack if the there is actionable tickets already in "Up Next". Depending on the new capacity, outcomes from this discussion could be:
- Pull in the next task related to a higher level priority (e.g. Epic) that was started in the sprint but not finished.
- Pull in lower priority and/or "smaller" tasks that can be started and completed in the remaining sprint time, including bugs and spike tasks.
- Rarely: pull in tasks for a new priority (e.g. part of an Epic). Generally avoided because these larger pieces of work should be tackled as a team.

Creating a New Sprint Board

When a sprint is completed, the team practices facilitator should create a new sprint board. Below is the process for doing so:

Obtain appropriate Phabricator permissions (see https://phabricator.wikimedia.org/project/profile/835/ for how to do this)
Go to https://phabricator.wikimedia.org/project/board/5858/ , our team workboard
Click "Subprojects" on the sidebar, which takes you to https://phabricator.wikimedia.org/project/subprojects/5858/
Click "Create Next Milestone" to the right (will be enabled when permissions go through). Name it in the following format: "DST-Sprint-X (YYYY-MM-DD to YYYY-MM-DD)"
Add details (a description is required) and hit "Create"
On the new board, hit "Workboard", then "create new workboard", then "import columns from existing workboard" and select an existing sprint board

Et voilà! A new board

Codex

General guidance:

Used as a “tag” to indicate that a task is related to Codex.
No status tracking happens in this board; rather, columns are used to categorize tasks (but this is rarely done).


COLUMN NAMES	DESCRIPTION
Inbox (Default)	All new requests are captured here. Should be reviewed/cleaned regularly.
Proposed New Components	Contains tasks for new components that have not yet been prioritized by a team.
Planned New Components	Contains tasks for new components that have been prioritized by a team or are in progress.
Proposed Component Updates	Contains tasks for updates to existing components that have not yet been prioritized by a team.
Planned Component Updates	Contains tasks for updates to existing components that have been prioritized by a team or are in progress.
Contributor Experience	Contains tasks related to improving the designer/developer experience.
Codex Adoption	Contains tasks related to improving the experience for new users of Codex.
Infrastructure	Contains tasks related to technical infrastructure.

Meetings & their purposes

Scrum Events

Each scrum event happens once per sprint (biweekly). The facilitator rotates according to Design System Team/Chores#Team Practices chores.

Sprint Planning + Refinement

Review outstanding tasks from the previous sprint and align on team capacity and goals for next 2 weeks.
Review, create, refine, and estimate relevant tasks that ladder up to the sprint goals.
Align on technical complexity, uncertainty, and overall effort.

Retrospective

Reflect and discuss ways to improve on how we work together.
Provide a safe space for team members to discuss issues without blaming or shaming.
Foster a culture of continuous learning and improvement.
Note: once per quarter, this meeting becomes an opportunity to do a Team Health Check.

Task Refinement

Refine and estimate tasks together to make the sprint planning meeting less demanding.
Gain shared context on upcoming work.

Sprint Review + Demos

Share what we have built and learned during the sprint, better enabling us to adjust our plans accordingly.

Break down silos between workstreams and identify opportunities for collaboration.
Celebrate the progress we have made together!
Share both completed work AND work-in-progress across all roles/functions.

Non-scrum events

The facilitator for non-scrum events rotates every three months according to Design System Team/Chores#Non-scrum meeting ownership.

Design Sync (weekly)

All DST designers attend, plus one engineer and optionally the PM and any other engineers as needed.
Discuss and align on topics related to the design of design tokens, components, patterns and guidelines.

Engineering Enclave (biweekly)

Usually only engineers attend.
Discuss technical topics in-depth.
Standing topics:
- If we're going to swarm, let's coordinate our swarming.
- What needs to be included in the next release?
- What should we do in our next live code review session?

Tea Time (weekly)

Enjoy some low-key social time together.
Get to know each other better.

Steering (weekly)

Catch things that fall between the functions and have a teamwide impact.

Specific topics: allocations, resources, hiring, capacity.

Front-End Standards Group (biweekly)

See Front-end standards group.

Strategy (monthly)

Discuss open questions around our product strategy and realign on the roadmap and OKRs.

Driver role

A driver is a designated individual who is responsible for moving forward a project or initiative.

Responsibilities:

Giving status updates in DST meetings
Reporting on the status of the project or initiative at DST sprint review meetings to ensure all necessary stakeholders or experts are informed and, if needed, involved.
Ensuring that blockers of the project or initiative are reported and addressed
Ensuring the work is properly represented in Phabricator
Coordinating the work of the project or initiative
Coordinating code review
Participating in cross-team meetings, or designating another DST member to attend

The driver is not responsible for:

Completing all of the work of the project or initiative. This may happen for smaller projects, but generally more than one person should be working on every project. “Work” may include design work, development work, Phabricator updates, documentation, communication, etc.
Making all decisions about the project or initiative. This may happen for some things, but decisions can and should be made as a larger group, or at least with input from a larger group.
Having all the answers about the project or initiative. The driver may attend a meeting then bring questions or information back to other team members or the entire team to discuss or address.
Doing all communication around the project or initiative. The driver may designate other individuals to handle parts of the project.

Driver selection

Identifying the need

A driver or pair of drivers may be designated for the following:

Large initiatives, e.g. CSS-only components or code splitting. For initiatives, much of the team will be working on the initiative, but the driver will be responsible for moving the initiative forward and coordinating work and communication.
Discrete projects, e.g. a new component or a collaboration with another team on a feature. For projects, more than 1 team member will likely be involved.
Single, large tasks, e.g. a new feature of an existing component or a new section of the style guide. For single tasks, it may just be the driver(s) doing the work, but they may still need to reach out to other team members for feedback.

If the initiative, project, or task involves both design and development, a driver from each role may be designated to work together.

Smaller tasks that can be completed by the assignee with review from another team member just need an assignee and not a formal driver

Selecting the driver(s)

Driver selection should be based on:

Who has capacity. Driver roles should be spread across the team as much as possible.
Who has interest, subject matter expertise, or a desire for education/experience.
The scope of the project.

Documentation

On Phabricator: Work that is identified as requiring a driver should be captured in Phabricator as an Epic on the DST Roadmap, with the drivers clearly listed in the task description and in the Phabricator "assignee" field if possible. For more design-driven work, like new components, the assignee should be a designer. For more engineering-driven work, like infrastructure enablement, the assignee should be an engineer.

Limits

So far there has not been a need to apply explicit limits on driver assignments. If needed in the future, some ideas are to put limits on the number of active projects with drivers, or the number of driver roles per team member.

Releasing

We follow the cadence outlined on the Release Timeline page, releasing a new version of Codex every 2 weeks on Tuesday. The team follows these norms for the release process:

Personnel

The role of "releaser" rotates through DST engineers. See the Chores page for the order and who did the latest release
If someone in a more eastern time zone is involved in the release, it should start earlier in the day on Tuesday if possible

Patch inclusion

On Monday, the week of a release, a "Codex release reminder" thread will be posted by Slackbot in the #design-system Slack channel. This is an opportunity to post open patches that you'd like to be included in the release and discuss when exactly the release will be done and who will review the patches.
If a patch is not open by the time this thread is posted, it will not be included in the release except in case of emergency. Emergencies must be agreed upon by the team. We place more importance on production code than the Codex docs site.
In case of an emergency, the team may decide to delay the release by a day. This should be communicated to Codex users. A release should not be delayed more than that, to ensure Codex users have time to test the latest release in MediaWiki before the train the following week.
The releaser has the right to reject an open patch if they do not feel comfortable merging it before cutting the new release.
From the time Slackbot posts the release reminder thread until the time the release is done, no patches should be merged in Codex except those that are targeted for the release. Other patches, and especially risky patches, should wait until after the release.

Code review

Participants and roles

Design System Team Tech Lead: submit patches, review code and resolve disagreements, +2 patches
Design System Team engineers: submit patches, review code, +2 patches
Design System Team designers: conduct design review, may +2 design-related patches
Contributors outside the DST: submit patches, review code, +2 some patches (see below for details)

Norms

Conduct

We value code review not only as an opportunity to prevent issues and maintain a healthy code base, but as a process that encourages collaboration, knowledge sharing, and growth. We follow these guidelines for a healthy code review culture and ask that all of our collaborators do so.

Code review ratings

We follow the definitions of the code review ratings (-2, -1, 0, +1, and +2) as outlined in the general Code review docs. We have a few additional norms around these ratings:

-1 is a clear signal that changes are required before the change can be merged. Generally, we give the person who applied the -1 a chance to review again after changes have been submitted. If that person isn't available in a timely manner, or if it is very clear that the concerns were addressed, someone else can confirm that the issues were resolved and merge the patch.
0 is used for general comments, questions, or non-blocking concerns. Only apply a -1 if there are blocking issues outlined in comments.
+1 is used liberally to show support for a patch that you do not want to merge for whatever reason. Multiple approvals of a patch offers encouragement and documents support for a code change.

Who can +2?

Most of the time, someone from the Design System Team will apply a +2 to merge a patch. That said, we welcome contributors from outside the team to +2 a patch if it's a minor or uncontroversial change, or if general approval of the patch has been demonstrated (e.g. via a +1 from a DST member).

If you are an author of the patch, you generally should not +2 that patch. We make exceptions for small changes, like rebasing, fixing a typo, updating the commit message, or optimizing an SVG. However, if you are not 100% sure, ask someone else to review before merging.

Unresolved comments

We use unresolved comments as a signal that a patch is not yet ready to be merged. This is especially helpful when we want to get design review before merging a patch. Before you merge something, review the unresolved comments and determine if any are blocking. If not, the patch can be merged and unresolved comments can be addressed in a future patch.

In-progress and experimental work

Often, we push code to gerrit that is not yet ready for code review or is not intended to ever be merged. To signal such a state, consider the following:

For a work-in-progress patch, use gerrit's "Mark as work in progress" feature. Other engineers should ignore the patch unless a review is specifically requested.
For a patch that should absolutely not be merged yet to prevent a negative consenquence/breakage, the patch author should add a -2 code review vote and a comment explaining why the patch should not be merged and when it could be merged. You can also use the "work in progress" feature in gerrit if applicable.
For a proof-of-concept that is not intended to be reviewed and merged but is only used for testing purposes, add [proof of concept] to the beginning of the first line of the commit. You can also add a -2 code review vote if desired. This is usually used for prototyping new features.
For a patch that is only meant for testing and affects an existing feature, add [do not merge] to the beginning of the first line of the commit message. You can also add a -2 code review vote if desired.

Live code review

Sometimes, it's easier to discuss a patch together than to rely on asynchronous comments in gerrit. Some examples:

When a new contributor has submitted a patch (especially a larger one)
When the reviewers are not familiar with the code that's being changed
For particularly large or complex patches

In these instances, we hold a live code review session, which follows one of these formats:

Reviewers review the change and leave comments before the meeting. During the meeting, the code author leads a discussion through the comments, and the team collectively decides how to resolve them.
During the meeting, the code author walks the reviewers through the patch before they complete a review. Reviewers can raise topics during the meeting but complete full code review later.

Code authors can suggest live code review for a patch. Otherwise, DST engineers identify topics for live code review at the preceding engineering enclave.

Onboarding

Onboarding as a new employee of the Wikimedia Foundation is a notoriously difficult and lengthy process. While each role has its own onboarding process and documentation, this section will focus on what the team can do to help new teammates onboard to our own processes and work.

Onboarding buddy(ies)

If applicable, someone on the team will be assigned to be the new teammate's onboarding buddy, or we may rotate this responsibility. Onboarding buddies should make sure to do the following:

Meet at least once weekly. Ask if the new teammate has any questions about onboarding, their work, or anything else. Check in on how they're feeling and ask if there's anything we can adjust to make the onboarding process easier. Help make them feel welcome!
Make it clear that you are available to chat asynchronously throughout the week as well
Help triage the new teammate's requests for help. Point them toward the right person, or set up a session yourself.
Look for opportunities to introduce the new teammate to folks across the Foundation. If you find one, start an email or Slack thread introducing the new teammate and the other person, setting context and expectations (e.g. "New Teammate has questions about X, and I thought you would be the right person to talk to them about that. Can you schedule a chat with them soon?")
For engineers: help the new teammate find good first tasks, and look for opportunities for the new teammate to pair program with other engineers

Meeting the team

In the first few weeks after the new teammate starts, everyone on the team should reach out and schedule a 1:1 to meet, get to know each other a bit, and talk about your role and how it relates to their role. This can overlap with context-setting sessions, or be a separate session.

If you can, try to attend a tea time or two during the new teammate's first few months. This is a great time to build trust and connection.

The new teammate should read these pages about how the team works:

Context setting

While there are standard onboarding sessions for Foundation- and movement-wide topics, we need to onboard the new teammate to our big-picture goals, current work, and team processes. Some of this can be done in an initial focused effort, and some will need to be done over time.

General context-setting

Be mindful during the new teammate's first few months that they are taking in a great deal of information and will need time to build historical knowledge. Here are some things we can all do to help:

During meetings, on Slack, or in Phabricator, pause to give some background when you discuss a topic that the new teammate may not have encountered before. Assume that they do not have this background info—they can stop you if they do, and you might be helping someone else on the team learn something they didn't know before either.
Check in with the new teammate, either immediately or later in private, to ask if they have any additional questions on a topic discussed in a meeting or elsewhere
Help create an atmosphere of sharing knowledge by asking your own questions publicly

Focused context-setting

The team should help cover several important topics in the new teammate's first few weeks via 1:1 sessions. The new teammate's manager or onboarding buddy can facilitate assigning these topics to people across the team, or leads/managers can be the default.

Roadmap overview (product manager)
Explanation of meetings and sprint processes
Engineering big-picture (tech lead)
Design big-picture (design lead)

Team chores

The new teammate should be placed at the end of the team chores rotation, so that they will go after everyone on the team has gone once before them. If they are an engineer, they should be placed at the end of the technical chores rotation as well.

↑ https://www.scrumalliance.org/about-scrum

[1] ttps://www.scrumalliance.org/about-scrum

[1]