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 work on mobile devices with small screens and no keyboard.
 * Software that implements user interfaces for key functionality should be designed to make such functionality work 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 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. (TBD)
 * 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.
 * Allow content to be accessed with high granularity.
 * Avoid any need for 3rd parties to process wikitext.
 * Design data formats and APIs to ensure data integrity through the integration of provenance information.

'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]


 * Create a modular software architecture with narrow and stable interfaces. Create reusable components.
 * Publish libraries that 3rd parties can freely use.
 * Build on top of reliable, documented, well-maintained open-source components.
 * Contribute upstream to tools and libraries we use.
 * Foster an ecosystem of 3rd party re-users (volunteer and professional) that encourages contribution.

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


 * Identify and explicitly model relevant entities and events (nouns and verbs).
 * Design all code for testability. Ensure coverage with tests that ensure compliance with the documented interface contracts.
 * Maintain comprehensive documentation, along with the code. Document the rationale behind design decisions.
 * Use the Continuous Integration development model.
 * Pay off Technical Debt in a timely manner.

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


 * Make the MediaWiki stack easy to deploy on standard hosting platforms.
 * Ensure that small MediaWiki instances can run in low-budget environments.
 * Make MediaWiki easy to install and upgrade.

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


 * Consider horizontal scalability on all levels of the architecture, especially for storage and query mechanisms.
 * Design MediaWiki as a system that can be decentralized and distributed.
 * Be resilient against spikes in system load and failure of backend systems.
 * Allow the identification of read-only and read-write HTTP request routes to optimize routing and caching.
 * Consider change management and operational overhead 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]


 * Be prudent about what data we collect, and disciplined about its retention.
 * Make it easy to keep systems updated and change configuration.
 * Isolate components to reduce attack surface while minimizing system complexity.
 * Build resilience against data corruption into the architecture.
 * Be responsive as well as proactive in ensuring security.