Core Platform Team/Initiative/Stability annotations/roadmap

Baseline

 * Manually compile a list of classes designed to be "newable" (value objects)
 * Manually compile a list of classes designed to serve as extensions points (base classes)
 * For each class, identify methods that are intended to be overwritten.
 * Manually compile a list of interfaces designed to be implemented by extensions
 * Apply the appropriate annotations to the code

This work is primarily based on knowledge of the codebase. Time needed: one week, two engineers, at least one with good knowledge of the codebase. Identifying methods designed to be overwritten takes most of the time.

Patches:


 * https://gerrit.wikimedia.org/r/c/mediawiki/core/+/579253
 * https://gerrit.wikimedia.org/r/c/mediawiki/core/+/579252

Stretch

 * For all extensions, find out which core classes they instantiate, which core classes they extend, and what core interfaces they implement or extend.
 * Ideally, build tooling to do this automatically.
 * For each such usage, decide whether that usage is legitimate.
 * If yes, apply the appropriate annotation to the code in core
 * If no, decide if we need to provide an alternative (e.g. a factory for instantiation)

One to three weeks for two engineers, depending on how confident we want to be that we didn't miss any edge cases.

Later

 * In CI, automatically detect when extensions use core code in unstable ways, based on the annotations of the core code.

Effort is to be determined. A first step would be to identify the appropriate static analysis tool.