- Stakeholder(s):
- Extension authors
- MediaWiki core developers
- MW Release manager (because of release schedule)
|
Problem:
- Per the new Stable Interface Policy, some aspects of MediaWiki that extensions do and should be able to rely on have become “unsafe”.
- MediaWiki core is lacking annotations that guarantee the stability of parts of the code that should be safe for extensions to use.
- If we do not add such the missing annotations now, nearly all extensions are going to be in violation of the policy, and rendering it moot.
- If we want to benefit from the freedom the new policy gives us after 1.35 is branched, we have to make sure it's actually applicable in practice, which means we have to document what extensions are still allowed to do, be adding the necessary annotations.
|
Solution:
- Add missing annotations to code documentation in MediaWiki that extensions should be able to rely on, before 1.35 is branched.
- Add support for the new tags into doxygen [already done].
|
Aligned Goals:
- Reduce Extension Interface Surface Area
- Improve Platform stability
|
Estimated Effort:
- Prep: 1 engineer, 1/2 sprint: preliminary inventory of newable classes, extensible classes, and implementable interfaces. [mostly done already]
- Focus: 2 or 3 engineers for 1 sprint, mostly reviewing existing code for intent and actual usage in extensions. The hardest part is deciding which methods should be stable for overriding.
- Close: 1 engineer 1 sprint (plus CR), to resolve remaining edge cases by changing extension code.
- Follow: 1 engineer occasionally, when problematic usages/needs are found in extensions.
|
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.
|
|
