Design Systems Team/Team Processes

"Continuous improvement is better than delayed perfection."

Scrum Principles
Design Systems Team (DST) uses the Scrum framework, 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
Estimate tasks chosen by the team:
 * Task creator describes the task at a high level. Team has a chance to discuss/clarify/refine.
 * Engineers & designers (depending on the task) select the number that correlates to their estimate of the task:
 * The basic assumption is that 1 point = ½ 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”). With that in mind, you can also use the following heuristics
 * 1 point = Small, ½ day. We feel we understand most requirements and consider it relatively easy.
 * 2 points = Small-ish, roughly a day. Straightforward but may have known potential gotchas.
 * 3 points = Medium, 1-2 days. We know what needs to be done, but there may be a few extra steps.
 * 5 points = Medium-large, 2-3 days. This is complex work, or work we don’t do very often. Will likely involve research or consultation.
 * 8 points = Large, ~1 week. Ideally completed in conjunction with another engineer to spread context and lift. May be a sign that a given task is too large and needs to be broken down further.
 * 13 points = Extra large, > 1 week. We need to break this down further before it can be brought onto the sprint board.
 * Estimate is added to the Phabricator task, and the task is moved into the next logical column/board.
 * 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 2-3 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.

Design-Systems-Product-Roadmap
General guidance:


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

Design-Systems-Team
General guidance:


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

Design-Systems-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 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-systems-standup Slack channel.
 * Generally, Phabricator tasks should go through triage & refinement in design-systems-team. However, sometimes tasks need immediate action - feel free to move these items into design-systems-sprint and let the team know in your standup.

* 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. Epic). Generally avoided because these larger pieces of work should be tackled as a team.

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.

Scrum Events
Each scrum event happens once per sprint (biweekly). The facilitator rotates according to Design Systems Team/Chores.

Sprint Planning

 * Review outstanding tasks from the previous sprint and align on team capacity and goals for next 2 weeks.

Refinement + Estimation

 * An opportunity mid-sprint to recalibrate our workload (e.g. spin out new tasks, move some to the backlog, swap sprint tasks for ones in "Up Next").
 * Review fleshed-out work and determine the relative story points for that work, OR send work back to the backlog for refinement.
 * 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.

Sprint Demos

 * Celebrate the progress we have made together!
 * Share both completed work AND work-in-progress across all roles/functions.
 * Share what we have learned during the sprint, better enabling us to adjust our plans accordingly.

Non-scrum events
The facilitator for non-scrum events rotates every three months according to Design Systems Team/Chores.

Design Sync (weekly)

 * Discuss and align on topics related to the design of design tokens, components, patterns and guidelines.

Engineering/Design Sync (weekly)

 * Venue for designers and engineers to problem-solve as a group.

Engineering Enclave (weekly)

 * 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.

Live Code Review (biweekly)

 * Engineers review a pre-selected patch or patches together.

Strategy (monthly)

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

Team Processes Task Force (monthly) Cancelled Indefinitely (yay!)

 * Ensure DST team processes are defined, socialized, and understood.
 * Facilitate improvements to team processes, such as:
 * Choosing and adhering to an Agile framework (scrum, kanban, etc).
 * Phabricator boards & workflows.
 * Meeting purposes & cadences.

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-systems-engineering 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.

Participants and roles

 * Design Systems Team Tech Lead: submit patches, review code and resolve disagreements, +2 patches
 * Design Systems Team engineers: submit patches, review code, +2 patches
 * Design Systems 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)

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 Systems 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).

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.

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:


 * 1) 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.
 * 2) 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:


 * Main team page
 * Team processes (this page)
 * Team norms

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.