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.