Page MenuHomePhabricator

Governance & Guidelines: Design System Code Contribution Guidelines
Closed, ResolvedPublic3 Estimated Story Points

Description

Background/Goal

Create and publish Design System Code Contribution Guidelines.

User stories
  • As a front-end developer, I understand the steps required to merge and/or update code related to the Design System.
Considerations
  • This process should also work for contributions from community developers
Requirements
  • There is a single source of truth for Code Contribution Guidelines that is publicly available
  • The Code Contribution Guidelines MUST include the following:
    • Steps for front-end developers to UPDATE/FIX existing Code, including who does code review, etc.
    • Steps for front-end developers to ADD/EXTEND CODE, including who does code review, etc.
    • Clear outlines of when to start, who should be involved, etc.
  • There is a single source of truth for each user story (aka artifact)
Acceptance criteria
  • There is a single source of truth for each user story (aka document)
  • All documentation should link back to a central Design System Portal/Wiki
  • Artifacts should be:
    • easy to read (limited jargon)
    • clear to follow (written as steps, checklists, visual diagrams, etc.)
  • Access to artifacts should NOT be restricted for viewing by target users (aka remove or update permissions as necessary)
Test scenarios

[N/A]

Open questions

[to come]

Event Timeline

The closest thing we have to this currently are the guidelines and contributing code pages on the Codex docs site.

It seems like this task is more about outlining our processes for submitting and reviewing code, is that correct? We already cover a lot of this in our contributing code docs, although we recently discussed adding more information about how our team handles code review (who performs reviews, how conflicts are resolved, how we use the gerrit rating system, what to expect in terms of timeline, etc) so that could be a good outcome of this task. Is there more we need to do here?

I would also strongly recommend that this all live in the contributing code docs, and not on-wiki as the task specifies. We can link to the Codex docs on-wiki in case potential contributors start there.

DAbad changed the task status from Open to In Progress.Aug 3 2022, 5:58 PM

@AnneT the scope of this ticket would include documenting the steps, workflows, and processes in relation to anyone trying to extend or contribute to components. In addition to code review there are a few other areas that could be added to this scope.

  • Risk Assessments:
    • As a system meant to be widely used by everyone, are certain types of contributions more risky than others? If so, do we handle in different ways?
    • Are there clear criteria to evaluate risk against from the code perspective?
    • What is the risk escalation process (aka notify tech lead, EM, DST, etc)
    • Do we ever lock-down particular components because of the risk level?
  • Code Review:
    • who performs reviews & when? Should a DST engineer always review or is it okay to have others code review?
    • how do we capture outcomes from reviews? How would we prioritize or resolve conflicts?
    • role of DST vs other product feature teams
    • how do we use gerrit rating system
  • How to contribute to the Design System without using codex:
    • Tips on how to leverage existing components in codex, without actually using codex
    • Tips on how to align non-codex components with the Design System as much as possible

Also, I updated the requirements to specify that documents should be publicly available vs on-wiki.

@DAbad great, thanks for outlining all of this. I'd like to get the other engineers' perspective on this, too (cc @Catrope @egardner @Volker_E), but it sounds like we might need three separate pieces of documentation:

  1. Documentation of our processes and standards, which includes everything you outlined in the first two bullets (risk assessments and code review) and the "code contribution workflow" section on the "contributing code" page. This should probably live on the Codex docs site. We might want to split this into multiple pages.
  2. Documentation of how to actually write code in Codex, which includes everything in our current "contributing code" docs except for the "code contribution workflow" section. This should definitely live on the Codex docs site.
  3. Documentation on working with the design system but not Codex (your third bullet point). This should probably live on-wiki.

We could link to the first doc from the second, to inform potential contributors where they can find information about our processes and standards, and recommend that contributors read the first doc before they contribute a component.

That's my proposal—happy to hear other solutions as well!

This sounds good to me, thanks for writing this up @AnneT. The current "contributing code" page is too large IMO, so splitting it up into multiple pages sounds like a good idea.

Our current contributing docs architecture is:

(Note that the first level is a section of the sidebar, the second is a page, and the third is headings within a page)

  • I. Contributing
    • A. Guidelines
      • i. Intro paragraph on different way you can contribute
      • ii. How to stay up-to-date
      • iii. Task tracking
    • B. Designing components (empty)
    • C. Contributing code
      • i. Links to general contribution guidelines and code design principles
      • ii. Link to code repo
      • iii. Code contribution workflow
      • iv. Development basics
      • v. Developing components
    • D. Working with TypeScript (contains a few sections that are irrelevant to this discussion)

I would recommend we change this to:

  • I. Contributing guidelines
    • A. Introduction
      • i. Intro paragraph on different way you can contribute
      • ii. How to stay up-to-date
      • iii. Task tracking
    • B. [Whatever docs we intend to create about the process of adding or updating components, etc]
      • [Section on code contribution workflow, which includes information about the different pathways for contributing code]
  • II. Developer docs
    • A. Introduction
      • i. Links to general contribution guidelines, component workflows, and code design principles
      • ii. Link to code repo
      • iii. Patch requirements
      • iv. Development basics
    • B. Developing components
      • i. Component basics
      • ii. Using the Vue sandbox for local development
      • iii. Writing styles
      • iv. Bidirectional script support
      • v. Inheriting attributes
    • C. Testing components
        • i. Intro to the ways we test components
        • ii. Unit tests
        • [Other testing stuff, e.g. link to manual testing process, using patchdemo, etc]
      • D. Component demos
        • i. Difference between Vue sandbox and VitePress site
        • ii. How the demo system works (current content of the "component demos" section)
        • iii. Demo standards and conventions
    • E. Working with TypeScript (current content of this page)

In order to achieve this structure, we'll need to do the following:

  • Restructure the sidebar to make a new section for "Developer docs" Done
  • Split the existing "contributing code" docs up according to the outline above Done
  • Add the code contribution workflow info to whatever docs we eventually create on component contribution workflows Done

Additionally, we need the following documentation on mediawiki.org:

  • How to work with Codex in MediaWiki Done
  • How to work within the design system without directly using Codex
AnneT set the point value for this task to 3.Sep 12 2022, 7:00 PM

Change 831631 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] docs: Split contributing code docs into multiple pages

https://gerrit.wikimedia.org/r/831631

Change 831631 merged by jenkins-bot:

[design/codex@main] docs: Split contributing code docs into multiple pages

https://gerrit.wikimedia.org/r/831631

Change 831947 had a related patch set uploaded (by Eric Gardner; author: Eric Gardner):

[mediawiki/core@master] Update Codex from v0.1.1 to v0.2.1

https://gerrit.wikimedia.org/r/831947

Change 831947 merged by jenkins-bot:

[mediawiki/core@master] Update Codex from v0.1.1 to v0.2.1

https://gerrit.wikimedia.org/r/831947

Change 831961 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] docs: Add link to code review process

https://gerrit.wikimedia.org/r/831961

Change 831962 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] docs: Link to Codex docs on mediawiki.org

https://gerrit.wikimedia.org/r/831962

Change 831961 merged by jenkins-bot:

[design/codex@main] docs: Add link to code review process

https://gerrit.wikimedia.org/r/831961

Change 831962 merged by jenkins-bot:

[design/codex@main] docs: Link to Codex docs on mediawiki.org

https://gerrit.wikimedia.org/r/831962

AnneT removed AnneT as the assignee of this task.EditedSep 14 2022, 1:22 PM

I've completed every part of this task that I can complete, including:

  • Refactoring the long "contributing code" page into multiple pages
  • Improving the explanation of contribution pathways
  • Documenting the team-wide code review process on mediawiki.org and linking to it from the Codex docs site
  • Linking to the MediaWiki-specific Codex docs from the Codex docs site

The remaining undocumented topics are risk assessment and how to use the Design System without using Codex.

ldelench_wmf subscribed.

I think risk assessment and how to use the Design System without using Codex could be broken out into separate followup tasks (I will do that); in the meantime moving this over to Product Sign-off for the completed scope!

Change 849191 had a related patch set uploaded (by VolkerE; author: VolkerE):

[mediawiki/core@master] Update Codex from v0.2.1 to v0.2.2

https://gerrit.wikimedia.org/r/849191

Change 849191 merged by jenkins-bot:

[mediawiki/core@master] Update Codex from v0.2.1 to v0.2.2

https://gerrit.wikimedia.org/r/849191