We want to invite contributors outside the WMF Design Systems Team to contribute to Codex, and have already had a couple of successful collaborations with WMF and WMDE engineers. We should draft standard processes for various types of collaborations in order to streamline the process and help contributors understand what to expect.
Collaboration levels
Collaborations could take many forms, and will land somewhere on this spectrum:
- Level 1: A small design update or code change. Examples: changing the color of spacing of something, fixing a bug in the code, or adding/changing a component demo. These contributions may only require planning in the form of a Phab task and a bit of discussion in the comments. DST would need to provide design or code review, likely on an asynchronous basis.
- Level 2: A small to medium new feature or change. Examples: adding the error state to the TextInput component, introducing the portrait layout for the Card component. These contributions would require some planning with the DST, either via Phabricator, chat, or a synchronous meeting. Design or code review may take several rounds and require a synchronous discussion (e.g. live code review).
- Level 3: A major new feature or significant change. Examples: adding infinite scroll to the Menu component, adding a brand new component. These contributions would require significant planning with the DST, developing a timeline for the work, regular check-ins, a QA plan, etc.
Processes
Level 1
Very minor collaborations will only require asynchronous discussion. This will mostly be in the form of discussion in Phab tasks, Figma, or Slack, plus code review.
Level 2
Small to medium changes may require the following:
DST roles
- Main contact: the primary contact and driver for this collaboration
- Designated designer: if needed, the designer that will answer questions and provide design support and review. May be the same as the main contact.
- Designated engineer: if needed, the engineer that will answer questions and provide code review. May be the same as the main contact.
Process
- New contributor contact
- Goal: To give the new contributor a leg up as they start working on Codex.
- Roles: Main contact
- Description: If this is a new contributor, an initial communication to provide them with the basic information they need to know to get started with Codex work. This could take the form of a summary in the docs that points them to the most important resources, or a quick meeting to review that information.
- Initial feature contact
- Goal: To confirm the scope of work, discuss implementation details, and agree on the level of support DST will give to the contributor based on their needs and our capacity
- Roles: Main contact, designer/engineer if needed
- Description: A DST rep should connect with the contributor to discuss the scope of the collaboration. This could happen in a Phab task or in a synchronous meeting. Inform the contributor how they should communicate with DST.
- Support and feedback
- Goal: To provide support when the contributor has questions and to review their work.
- Roles: All
- Description: The DST rep (or other DST members) will be available to respond to questions in Slack, Figma, Phab, or Gerrit. As work is completed, the DST rep will provide design and/or code review.
Level 3
Major changes will require more involvement to lead to a successful collaboration.
Roles
- Main contact: the primary contact and driver for this collaboration
- Designated designer: if needed, the designer who will answer questions and provide design support and review. May be the same as the main contact.
- Designated engineer: if needed, the engineer who will answer questions and provide code review. May be the same as the main contact.
- Secondary code reviewer: a second engineer who will be available for code review when the primary engineer needs another opinion
Process
Note that most of this could be done asynchronously if necessary, but synchronous meetings allow for clear and efficient communication and trust-building.
- New contributor contact
- Goal: To give the new contributor a leg up as they start working on Codex.
- Roles: Main contact
- Description: If this is a new contributor, an initial communication to provide them with the basic information they need to know to get started with Codex work. This could take the form of a summary in the docs that points them to the most important resources, or a quick meeting to review that information.
- Creation of scope of work and timeline
- Goal: To finalize a clear scope of work before the collaboration begins (or as a first step).
- Roles: Main contact, designated designer, designated engineer
- Description: DST members should work together (and with the contributors if possible) to write a clear scope of work in Phabricator that describes what will be completed during the collaboration period. The team should also work with the contributors to set a timeline for the work, pulling in PMs, PgMs, and EMs as needed.
- Kick-off meeting
- Goal: Introductions + discuss details of collaboration
- Roles: All relevant DST members and contributors (including PMs, PgMs, and EMs as needed)
- Description: Led by the main contact, the relevant DST members and contributors will meed to review:
- Goals of contributors and DST
- Review of deliverables
- Roles and responsibilities
- Available working hours of those involved
- Planned meeting cadence
- Communication channels
- Task breakdown meeting
- Goal: Create common, detailed understanding of the work that will be completed
- Roles: Main contact, DST designer/engineer
- Description: Led by main contact, all collaborators dig into the task(s) and discuss the details of implementation. Contributors can ask questions to ensure they understand where to start and how the work will be completed. DST members can bring up considerations and recommendations. For larger features, break down into smaller tasks. Determine how to fit the work into the timeline.
- Regular check-ins.
- Goal: Provide space to check in on work in progress, shift scope of work if necessary
- Roles: Main contact, DST designer/engineer
- Description: If needed, meet regularly (once a week?) to check in on the work, problem solve, and pivot the scope if needed. These meetings can help keep the work on track and moving. Try to identify anything that the contributors could pass over to DST so they can focus on the main goals of the collaboration.
- Support and feedback
- Goal: To provide support when the contributor has questions and to review their work.
- Roles: All
- Description: The DST rep (or other DST members) will be available to respond to questions in Slack, Figma, Phab, or Gerrit. As work is completed, the DST rep will provide design and/or code review. Designated engineer should prioritize code review and pull in the secondary code reviewer as needed. Designated engineer should ping designated designer for design review and QTE for QA as needed.
- Wrap-up
- Goal: To decide how to handle outstanding work and collect feedback
- Roles: Main contact
- Description: Main contact will meet with contributors to review the collaboration. Determine how to handle unfinished work: can the contributors continue the work, or should they pass it to DST members? How will any design changes or bug fixes be handled? Collect feedback on the collaboration from the contributors by asking directly or sending a survey.
Sample survey questions
- What went well? What should we keep doing in future collaborations?
- What was challenging or frustrating? What held back the collaboration from being as successful as it could have been?
- What should we do differently in future collaborations?
- Overall, how satisfied are you with the collaboration and its outcomes?
Acceptance criteria
- Review processes with DST, update, and finaliize
- Post these somewhere other than Phab
- Open subtasks for any other work (e.g. creating a "quick start" for Codex contribution