Wikimedia Engineering/Project documentation howto

New approach in Phabricator

 * From Guillom

Until October 2014, most WMF project documentation and planning was being done on mediawiki.org. We had roadmaps, project pages, status pages etc. there. The system was a bit clunky but it mostly worked.

Our move from Bugzilla to Phabricator brought a lot of opportunities to simplify technical project management, and we're now in a place where we can retire the old system.

In practice, this means:
 * heavily relying on the roadmap: /tag/roadmap/
 * using #notice to tag other tasks and changes likely to impact users.

What this means for developers working on WMF engineering projects:


 * You should read the Roadmap description if you haven't yet: project/profile/1109/ ; The roadmap is the best way for people to keep up-to-date with what is happening in Product & Engineering. From there, anyone can see who's doing what and when, and subscribe to projects they're interested in.


 * When you're working on a Phabricator task, you should feel free to generously comment on that task with updates.


 * People can follow your progress on the task, which means... we don't need the monthly reports any more! [0]


 * Anyone should feel free to request an update about a task by adding a comment there.


 * If your team hasn't moved to Phabricator yet, I suggest you create tasks in Phabricator for the biggest items, add them to the roadmap if appropriate, add the relevant Trello (or other) link, and add status updates.


 * When a change is likely to affect users, add the #user-notice tag to the task. If it's likely to affect developers, add #developer-notice. If you're not sure or are in a rush, just add #notice and it will be triaged into the appropriate sub-tag. Items flagged with #user-notice will be announced in the weekly technical newsletter.


 * Any task added to the roadmap is automatically added by Phabricator to the #notice tag as well to save you time (T93599).

My [Guillom's] plan going forward is to:


 * Retire the Wikimedia Engineering portal and soft-redirect it to the roadmap.


 * Subst: all the previous monthly reports, so the transclusions don't horribly break when we edit/remove templates from project pages.


 * Update the various Wikimedia engineering templates to display historical on project pages. If a project page is still useful, then the template can be removed.

= Old Engineering project pages on mw.org =

The Wikimedia Foundation aims to work as transparently as possible, and this includes development and operations work (collectively referred to as "engineering").

Engineering projects are documented publicly whenever possible. In particular, development projects each get a "project page" on this wiki.

The project page is the central venue for the project team to coordinate their efforts publicly, and for the rest of the world to learn about what is being done and how they can help. MediaWiki development relies heavily on volunteers. Project pages allow you to make it easier for volunteers to find information about your projects, and to get involved.

Project pages usually include basic information about the project (name, description, team, dates, etc.) and links to other documents (design and architecture docs, etc.). It's really up to you and your team to find how to best use the project page. Just know that the more open you are, the more engaged the community will be about your work.

A very important piece of information for a project is its current status; status updates are recorded in a subpage and surfaced in many places, including the monthly engineering report.

This page provides information on how to create, use and update project documentation pages. Feedback and questions are appreciated on the talk page.

Features, Mobile & Platform groups

 * 1) Go to your team hub: Features, Mobile, Platform or Analytics
 * 2) Click the Edit button.
 * 3) Add a line for your new activity similar to the existing ones in the list.
 * Syntax:
 * 1) Save the page.
 * 2) Click the red link labeled "Create a project page for this activity".
 * 3) Fill in the fields of the template according to the instructions, and save the page. This will add more boiler

Other groups
If your group doesn't have a hub:
 * 1) Enter the name of the activity in the field below and press the button:
 * 2) Fill in the fields of the template according to the instructions, and save the page. This will add more boilerplate content.
 * 3) If appropriate, remove the unneeded elements on the page, and add links / content specific to your activity
 * 4) Add your new activity to the Wikimedia Engineering portal:
 * Syntax:  (in the appropriate section)
 * 1) Add your new activity to the |next monthly engineering report (in the appropriate section). The date is the last day of the month the report covers, in ISO 8601 format.
 * Syntax:
 * Syntax:

Features, Mobile, i18n, E3 & Platform

 * 1) Make sure you have enabled the WMF Project Status Helper gadget in your preferences. If you haven't, check the appropriate box and save your preferences.
 * 2) Find your project in the |next report
 * 3) Click the   link next to your project; this should open an overlay called Project status helper.
 * 4) Check that the correct project was selected from the drop-down menu.
 * 5) Check that the Include in Monthly report? box is checked (the date doesn't matter).
 * 6) Enter your status update in the "Description" field, preview, and publish. You're done!

Operations, Wikidata & Offline
Edit the |next monthly engineering report directly. You won't have the nifty overlay.

Features, Mobile & Platform groups

 * 1) Make sure you have enabled the WMF Project Status Helper gadget in your preferences. If you haven't, check the appropriate box and save your preferences.
 * 2) Go to your team hub: Features, Mobile or Platform.
 * 3) Find your project in the list.
 * 4) Click   on the right; this should open an overlay called "Project status helper".
 * 5) Check that the correct project was selected from the dropdown menu.
 * 6) Check the date.
 * 7) Enter your status update in the "Description" field, preview, and publish.

How to edit the activity information (team, dates, etc.)

 * 1) Go to your team hub: Features, Mobile or Platform.
 * 2) Find your activity in the list.
 * 3) Click   in the Description or Team column''

You can also edit the project page directly: Go to the project page, edit and save.