Core Platform Team/Initiative/Stability annotations/roadmap

From mediawiki.org

Baseline[edit]

  • 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:

Stretch[edit]

  • 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[edit]

  • 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.