MediaWiki

Core Platform Team/Initiatives/Stability annotations

< Core Platform Team | Initiatives
Stability annotations
Product Owner:
Technical Contact: Daniel Kinzler
Status: Completed
Initiative Vision: Read Edit
Initiative Description:
Epics, User Stories, and Requirements:
Time and Resource Estimates:
Open Questions:
Documentation Links:

Initiative Vision

< Initiatives

Vision:
  • Extension authors have clear stability guarantees for different parts and aspects of MediaWiki core
  • MediaWiki core developers have clear documentation about which parts of the code require a deprecation process
  • 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.



Subpages




Description of the stability annotation initiative.

Author: Daniel Kinzler

Interested Collaborators/Reviewers: Petr, Nikki

Vision:

  • Extension authors have clear stability guarantees for different parts and aspects of MediaWiki core
  • MediaWiki core developers have clear documentation about which parts of the code require a deprecation process

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.

Deployment: n/a

Testing: n/a

Rollback: n/a

Subpages

Retrieved from "https://www.mediawiki.org/w/index.php?title=Core_Platform_Team/Initiatives/Stability_annotations&oldid=6679002"