Page MenuHomePhabricator

[ES-M1] Expand developer documentation in the EntitySchema Extension
Closed, ResolvedPublic3 Estimated Story Points

Description

Currently, the developer documentation in the EntitySchema extension's README.md is quite slim and does not reflect all the common development activities that are required for day to day development.

To ensure proper onboarding to the EntitySchema extension's development (which will impact analyzability) we should ensure we document both the development setup of the extension, and common day-to-day activities.

Acceptance Criteria:

  • Installation instructions are updated to reflect our current development workflows with the mwcli tool
  • Instructions for running PHP unit tests are included with example commands
  • Instructions for running PHP linting and static analysis (phan) locally are detailed with example commands
  • Instructions for running JS linting locally are detailed with example commands
  • Instructions for running Selenium tests locally are detailed with example command

Event Timeline

Prio Notes:

  • Impact areas: Analyzability
  • Does not affect end users / production
  • Does not affect development efforts
  • Affects onboarding efforts
  • Does not additional stakeholders
ItamarWMDE renamed this task from Expand developer documentation in the EntitySchema Extension to [ES-M1] Expand developer documentation in the EntitySchema Extension.Mar 2 2023, 8:06 AM
noarave set the point value for this task to 3.Mar 9 2023, 10:01 AM
noarave moved this task from Unified DOT Backlog to Sprint-∞ on the Wikidata Dev Team board.

Change 898740 had a related patch set uploaded (by Michael Große; author: Michael Große):

[mediawiki/extensions/EntitySchema@master] Add more detailed installation instructions to the README

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

Change 900364 had a related patch set uploaded (by Michael Große; author: Michael Große):

[mediawiki/extensions/EntitySchema@master] Add section about browser tests to the README

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

Change 901207 had a related patch set uploaded (by Michael Große; author: Michael Große):

[mediawiki/extensions/EntitySchema@master] Add Readme section about updating dependencies

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

Change 898740 merged by jenkins-bot:

[mediawiki/extensions/EntitySchema@master] Add more detailed installation instructions to the README

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

Change 901207 merged by jenkins-bot:

[mediawiki/extensions/EntitySchema@master] Add Readme section about updating dependencies

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

Change 900364 merged by jenkins-bot:

[mediawiki/extensions/EntitySchema@master] Add section about browser tests to the README

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

I have a few notes:

Installation instructions:

  1. The docs begin by assuming the engineer reading them knows (and has) a local MediWiki instance. I'm not sure this is a safe assumption to make, and would feel the instructions are more complete if we at least link to the mwcli installation and MediaWiki setup instructions (on the Mwcli pages in mediawiki.org).
  2. As fresh node is available through mwcli: mw dev mediawiki fresh, I feel like for consistency, cohesion and simplicity, we should use the mwcli version in our instructions as well (instead of directing engineers to install another tool).

Change 904552 had a related patch set uploaded (by Michael Große; author: Michael Große):

[mediawiki/extensions/EntitySchema@master] Clarify that MediaWiki is a prerequisite in the README

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

Change 904552 merged by jenkins-bot:

[mediawiki/extensions/EntitySchema@master] Clarify that MediaWiki is a prerequisite in the README

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

Change 904555 had a related patch set uploaded (by Michael Große; author: Michael Große):

[mediawiki/extensions/EntitySchema@master] More consistently recommend mwcli in README instead of fresh-node

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

Change 904555 merged by jenkins-bot:

[mediawiki/extensions/EntitySchema@master] More consistently recommend mwcli in README instead of fresh-node

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

ItamarWMDE updated the task description. (Show Details)

\o/ Looks great, thank you!