Wikimedia Technical Committee/MediaWiki Platform Architecture Principles/Draft 9-2018

The Wikimedia Technical Committee believes the following principles and requirements SHOULD guide the Platform Evolution Program and other Wikimedia engineering endeavors.

These principles and requirements are derived from strategic and operational goals of the organization, as understood and interpreted by TechCom. This document is not intended to define these goals, it merely re-states them to provide a rationale for the engineering principles we set forth. That is to say, each goal is the input from which the principles listed below it are derived.

Goal 1: Make content available to users, in a form suitable for their devices, the connectivity they have, in a language they speak. [Equity / Readers, Editors]


 * Software that implements user interfaces for key functionality SHOULD be designed to make such functionality available on mobile devices with small screens and no keyboard.
 * Software that implements user interfaces for key functionality SHOULD be designed to make such functionality available on mobile devices with limited connectivity.
 * Software that implements user interfaces SHOULD be designed to adapt the representation of content to the client device’s capabilities.
 * Software that implements user interfaces SHOULD provide consistent internationalization across platforms and follow accessibility guidelines.

Goal 2: Empower contributors to collaboratively grow and curate content, and to build the tools that they need to do so. [Equity / Editors, Power-Users, Admins]


 * Ensure the ability to contribute for a variety of situations, abilities, and devices. ((DEL))
 * Our software SHOULD provide extension points that empower the community with ways to develop workflows using scripting languages, and ensure safety and maintainability of custom scripts.
 * Software that manages or interact with user editable content SHOULD support close integration of various kinds of content.

Goal 3: 'Provide APIs that allow 3rd party interfaces to efficiently interact with wiki content. Provide reusable data that can be processed in bulk by 3rd party tools.' [KAAS, Sustainability / 3rd party developers]


 * Public APIs of our services SHOULD be modeled around abstract use cases, not catering to a specific user interface.
 * Our software SHOULD be designed in a way that makes all content and public meta-data available as structured and semi-structured data.
 * Data we offer for re-use SHOULD use clearly specified, stable data schemas based on widely used open standards.
 * Public APIs SHOULD allow access to content with high granularity.
 * APIs SHOULD be designed to avoid any need for 3rd parties to process wikitext.
 * Data formats and APIs that provide access to user generated content SHOULD be designed to ensure verifiability through the integration of provenance information.
 * Data formats and APIs that provide access to user generated content SHOULD be designed to provide easy access to all necessary licensing information. ((NEW))

'Goal 4: Provide an open-source software stack that can be easily used, modified, and extended by others. Be part of the ecosystem of the tools and libraries we use.' [FLOSS, Equity / 3rd party developers]


 * Software components SHOULD be designed to be reusable.
 * Our software architecture SHOULD strive to be modular, with components exposing narrow, stable interfaces.
 * Publish libraries that 3rd parties can freely use.
 * Our software SHOULD be built on top of reliable, documented, well-maintained open-source components.
 * We SHOULD contribute upstream to tools and libraries we use.
 * Our software architecture and development processes SHOULD be geared towards building an ecosystem of 3rd party re-users and contributors (volunteers and professionals).

Goal 5: Ensure programmer productivity by maintaining a code base that can be understood without needless difficulty and modified with confidence. [Sustainability, FLOSS / developers]


 * Our software architecture SHOULD reflect a conceptual model that clearly defines relevant entities and actions (nouns and verbs).
 * All code SHOULD be designed for testability.
 * Development processes SHOULD ensure coverage with tests that enforce compliance with the documented interface contracts.
 * Comprehensive documentation SHOULD be maintained along with the code.
 * Documentation on all levels SHOULD explain the rationale behind specific design decisions.
 * Software development SHOULD follow the Continuous Integration model.
 * Technical Debt SHOULD be made consciously, documented and tracked explicitly, and payed off in a planned timely manner.
 * MediaWiki SHOULD be easy to install and upgrade in a development environment.

Goal 6: Provide a web application that can be freely used to collaboratively collect and share knowledge. [FLOSS, Equity / wiki-owners]


 * The MediaWiki stack SHOULD be easy to deploy on standard hosting platforms.
 * Small MediaWiki instances SHOULD function in low-budget hosting environments.
 * MediaWiki SHOULD be easy to install and upgrade without much technical knowledge, and with the risk of losing content or disrupting operation.

Goal 7: Ensure the continued availability and performance of WMF projects through scalable and resilient system design. [Scalability, Resilience, KAAS / Users, Opsen]


 * Horizontal scalability SHOULD be a design goal on all levels of the architecture, especially for storage and query mechanisms.
 * MediaWiki as a platform SHOULD evolve into a decentralized and distributed architecture. ((WHAT))
 * Our software and infrastructure SHOULD be designed to be resilient against spikes in demand and failure of backend systems.
 * Services and APIs SHOULD be designed to allow the identification of read-only and read-write HTTP requests to optimize routing and caching.
 * Change management and operational overhead SHOULD be a key consideration in system design and technology choice.

Goal 8: Ensure the data integrity of the content on WMF systems, and protect the privacy of our users. [Security, Privacy / Users]


 * Our software systems SHOULD be designed to only collect data we need, and retain it only as long as necessary.
 * Our software and infrastructure SHOULD be designed in such a way to prevent unauthorized access to sensitive information, and to minimize the the impact of individual components getting compromised.
 * Our system architecture SHOULD isolate components to reduce attack surface while minimizing system complexity.
 * Resilience against data corruption SHOULD be a design goal for our system architecture, and be built into the software we write.
 * Tools and processes SHOULD be designed to allow us to be responsive as well as proactive in ensuring security.
 * Our deployment infrastructure and dependency management SHOULD make it easy to keep system components up to date.
 * Our deployment infrastructure SHOULD make it easy to change configuration settings without disruption.