Technical Collaboration Guidance/Vision

From mediawiki.org

The Technical Collaboration Guideline aims to become a set of recommendations followed by Wikimedia Foundation Product teams and Wikimedia communities to partner in software development. This document describes the pieces involved in this collaboration, and how they can work together.

Development flow[edit]

Imagine Development river flowing quietly but decidedly from the Lake of Ideas to the Sea of Deployments.

Imagine Project boats following the current or sailing up in this navigable river without waterfalls.

Imagine bridges across the river, each one a specialized Checkpoint, where people interested can watch Project boats as they approach.

Project boats show their decks while crossing slowly under the Checkpoints, and continue their journey if nobody raises objections.

When objections are raised, they are discussed with the crew, who may stop the boat to fix the problems or sail back to previous stages.

Sometimes Project crews and some watchers agree to disagree. The crew takes note, hands are shaken, and the journey continues. They will meet again at the river mouth, before entering the Sea of Deployments.

At the Bay of Communities, hundreds of settlements can be seen. Project boats visit first the communities that want to be visited first, and continue with the silent majority.

Finally, Project boats visit the communities with issues still unresolved. Hands are shaken again, discussions are held again, and at the end these communities decide whether the issues are resolved or whether a new visit in the next season is still in order.

Starting a project[edit]

A new project begins when an individual or a team takes an initial idea and starts defining a plan to implement it. Ideas may come from problems identified or opportunities to be explored, and they may be proposed by anyone through channels like Phabricator or IdeaLab.

Starting a project with the goal of deploying it in Wikimedia is a very serious matter, directly proportional to the user impact and expected budget. The more disruptive and expensive the plan, the more it is required to be checked against the mission, principles, strategy, annual plans, supported technologies...

The development flow needs to allow room for experimentation. Without experimentation, Wikimedia would not exist. Small adventures from idea to prototype are encouraged, as long as it is understood that the route from prototype to deployment will be more complex, and may not happen at all.

The development flow needs to allow for community collaboration. Without this collaboration, Wikimedia would not exist either. Preparing an initial draft privately is an option, as long as project promoters are ready to reconsider their ideas based on feedback received after the publication of their draft.

Checkpoints[edit]

Product teams work better in an agile context where experimentation, iterations and flexibility are the norm. Volunteers in wiki communities can understand these principles well, but they cannot afford to participate in the daily life of projects. Checkpoints allow projects to get the communities and other stakeholders involved, influencing their next steps.

Checkpoints happen when a project has a new deliverable that welcomes public feedback:

  1. A project proposal.
  2. A design concept.
  3. Translatable content.
  4. A prototype.
  5. A release plan.
  6. A beta in production.

Calls for feedback[edit]

Projects make calls for feedback at every checkpoint. They do it in a systematic way, using the same channels and the same principles for processing feedback and deciding next steps.

Volunteers can subscribe to all calls for feedback from a specific project (i.e. Flow). They can also subscribe to all calls of feedback of a certain type (i.e. design reviews). This allows the participation of more volunteers with limited time, interested in a specific project or focus.

The calls for feedback are common to all stakeholders, including communities and other WMF teams.

Ideally, calls for feedback should include calls for contributions as well, pointing to tasks that welcome volunteers.

Blockers[edit]

Calls for feedback focus on finding potential blockers. Smaller problems and requests are also welcome, but they will be put aside when potential blockers are found.

Blocking a project is a serious matter. Blockers proposed need to have a solid argumentation. They must be discussed until a decision is made. Blockers can be declined by the project team, who will need to provide a solid argumentation too.

Project information[edit]

All projects have a wiki page with an overview and a standard infobox containing their basic information: Phabricator links, contact details, subscription, and checkpoints passed / pending. Users can follow the checkpoint links to understand quickly the development status of a project.

Checkpoint information[edit]

All checkpoints have a wiki page with an overview, subscription, and up to date information about the projects that are running a call for feedback and the ones that passed/failed it.

Community decisions[edit]

Communities have two ways of controlling the products and major features being deployed in their wikis:

  1. Timing of the deployment, requesting to be among the early adopters or among the late / last adopters. Most features are deployed by waves, and this provides flexibility to projects very interested or very skeptical about a specific feature.
  2. Opt out based on blockers accepted by the development team that have clear community consensus. The hypothesis is that most of these blockers will either be solved through deployment waves, or will stand and stop a feature for all Wikimedia projects.