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:
 * Tasks in the “Up Next” column of our main workboard, starting with those marked high priority.


 * Task creator describes the task at a high level. Team has a chance to discuss/clarify.
 * 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.

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! = Something is broken and needs to be fixed immediately, setting anything else aside. This should meet the requirements for issues that hold the train.
 * High = Complete this month.
 * Medium = Complete this quarter (i.e., within the next three months).
 * Low = Complete next quarters (i.e., within the next six months or more).

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.

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

 * Align on team capacity/goals for next 2 weeks

Estimation

 * 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
 * Create expectations around how challenging or uncertain specific tasks are in order to better forecast sprints long-term (release planning, if applicable)
 * Get a sense of how much the team can plan and commit to in a sprint by using historical velocity
 * Opportunity to get clarity around work (e.g., "why do you think this is 5 story points and another engineer thinks this is 1 story point?")
 * Estimation can drive prioritization (low-hanging fruit might change prioritization, for example)
 * A way for us to understand and track our work
 * Helps keep accurate trends of our ability to complete work

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

Sprint Demo

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

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