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:

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.