Page MenuHomePhabricator

Document Skin API and their stability, if any (including Vector)
Closed, ResolvedPublic

Description

MediaWiki 1.35+'s Stable Interface Policy is restrictive in what it considers a stable interface and, generally, requires that developers be explicit about what "stable" actually means. The good news is that our codebases are mostly unstable by default. However, being explicit about what is unstable can also help. For example (but not to single anyone out), it would inform conversations like https://gerrit.wikimedia.org/r/c/mediawiki/skins/Vector/+/580591/3/includes/VectorTemplate.php#58

I propose that we:

  • Mark all classes as unstable, i.e. @unstable
  • Mark all classes as @internal

Related detail from @Krinkle:

  • @final annotation has no standard meaning in our code base. To enforce non-extendability use final in the code itself.
  • @unstable means the class is experimental but planned to become stable. If that's not the case, use @internal instead.

Context

  1. No classes extend SkinVector: https://codesearch.wmflabs.org/search/?q=extends%20SkinVector
  2. No classes extend VectorTemplate: https://codesearch.wmflabs.org/search/?q=extends%20VectorTemplate

Related discourse on final methods in wikitech-l

Event Timeline

Seems like a sensible activity to me!

@volatile

Can you give an example of something you would consider volatile?

👍 I like what this ticket proposes

Can you give an example of something you would consider volatile?

Thanks for asking. I'd thought that I'd documented a class as @volatile before but now I can't find it. I've removed it from the proposal.

Change 583358 had a related patch set uploaded (by Jdlrobson; owner: Jdlrobson):
[mediawiki/core@master] setupTemplate should be protected

https://gerrit.wikimedia.org/r/583358

Jdlrobson renamed this task from Document Vector's API and its stability, if any to Document Skin API and their stability, if any (including Vector).Mar 25 2020, 3:08 PM

Change 583365 had a related patch set uploaded (by Jdlrobson; owner: Jdlrobson):
[mediawiki/skins/Vector@master] Document setupTemplate method and mark Vector as @final

https://gerrit.wikimedia.org/r/583365

Change 583358 merged by jenkins-bot:
[mediawiki/core@master] setupTemplate should be protected

https://gerrit.wikimedia.org/r/583358

Change 583365 merged by jenkins-bot:
[mediawiki/skins/Vector@master] Document setupTemplate method and mark Vector as @final

https://gerrit.wikimedia.org/r/583365

Niedzielski added a subscriber: Niedzielski.

I'm adding Desktop Improvements. This task is already tagged Vector and related discourse has come up in a number of DIP patches already.

Given @Krinkle's feedback (see T248399#6032327), it appears that annotating all classes @internal is sufficient.

Change 618160 had a related patch set uploaded (by Jdlrobson; owner: Jdlrobson):
[mediawiki/skins/Vector@master] Document stability of undocumented classes

https://gerrit.wikimedia.org/r/618160

Welcome back @phuedx - this task has stagnated for some time :) Looking at Vector now we only have 3 undocumented classes. Hopefully this patch takes care of those!

Change 618160 merged by jenkins-bot:
[mediawiki/skins/Vector@master] Document stability of undocumented classes

https://gerrit.wikimedia.org/r/618160

Change 618265 had a related patch set uploaded (by Phuedx; owner: Phuedx):
[mediawiki/skins/Vector@master] documentation: Align @package annotations

https://gerrit.wikimedia.org/r/618265

Change 618265 merged by jenkins-bot:
[mediawiki/skins/Vector@master] documentation: Align @package annotations

https://gerrit.wikimedia.org/r/618265