Core Platform Team/Initiative/Architecture documentation

Initiative for documenting of architectural structure of MediaWiki core.

Author: Daniel Kinzler

Interested Collaborators/Reviewers: tbd

Vision:


 * Developers have guidance about what layers, domains, and patterns exist in MediaWiki core, how they relate, and what constraints they impose.
 * Developers have a clear sense of "where they are" in the source code, relative to other code, when reading the documentation of a class.
 * Developers get notified when their code violates architectural constraints.

Stakeholder(s):


 * MediaWiki core developers
 * Architects

Problem:


 * We don’t impose constraints on what part of the code can access what other part of the code. This leads to structural problems such as cyclic dependencies.
 * We don’t offer a pattern language that would allow engineers to synthesize solutions in a consistent way, resulting in ad-hoc designs.

Solution:


 * On mediawiki.org, create pages that describe the layers, domains, and patterns used in MediaWiki code. The documentation should reflect current reality, and explain which changes we want to make, and what future structure we aim for.
 * Use doxygen tags to associate each class in MediaWiki core with the layer and domain it belongs to, and any patterns it uses. The tag values should simply be the URLs of the wiki page describing the layer, domain, or pattern.
 * Add support for the new tags into doxygen.

Aligned Goals:


 * Make MediaWiki easier to understand
 * Improve Platform stability

Estimated Effort:


 * Prep: 1 engineer, 1/2 sprint: define a preliminary set of layers, domains, and patterns on mediawiki.org [mostly done already]
 * Focus: 2 or 3 people for 1 sprint, doing two things: (a) going through key parts of the code base, adding architecture tags, trying out the proposed structure (b) writing, reviewing and discussing on-wiki descriptions of the layers, domains, and patterns. Ideally a tech writer would be involved early on to provide guidance for the documentation structure and wording.
 * Close: 2 people 1 sprint going over unclear cases and open discussions and resolve them.
 * Follow: There are about a thousand classes to tag. Most will be trivial, some will be tricky. If we assume a single person can tag 100 classes a day doing nothing else, that would be one sprint. Realistically, it will probably take three or four sprints until we have gone through all classes and sorted out all questions. We may want to continue with extensions (roughly as many classes again).

Risk assessment:


 * Low. Only documentation is changed.
 * However, merge conflicts may arise when annotations are added to methods or classes that get removed or renamed by other patches concurrently under review. This may make interfere with selectively reverting such patches.

Deployment: n/a

Testing: n/a

Rollback: n/a