Hi all!
Since the new Stable Interface Policy[1] has come into effect, there has been
some confusion about when and how the deprecation process can be accelerated or
bypassed. I started a discussion about this issue on the talk page[2], and now
I'm writing this email in the hope of gathering more perspectives.
tl;dr: the key question is:
Can we shorten or even entirely skip the deprecation process,
if we have removed all usages of the obsolete code from public
extensions?
If you are affected by the answer to this question, or you otherwise have
opinions about it, please read on (ok ok, this mail is massive - at least read
the proposed new wording of the policy). I'm especially interested in the
opinions of extension developers.
So, let's dive in. On the one hand, the new (and old) policy states:
Code MUST emit hard deprecation notices for at least one major
MediaWiki version before being removed. It is RECOMMENDED to emit
hard deprecation notices for at least two major MediaWiki
versions. EXCEPTIONS to this are listed in the section "Removal
without deprecation" below.
This means that code that starts to emit a deprecation warning in version N can
only be removed in version N+1, better even N+2. This effectively recommends
that obsolete code be kept around for at least half a year, with a preference
for a full year and more. However, we now have this exception in place:
The deprecation process may be bypassed for code that is unused
within the MediaWiki ecosystem. The ecosystem is defined to
consist of all actively maintained code residing in repositories
owned by the Wikimedia foundation, and can be searched using the
code search tool.
When TechCom added this section[3][4], we were thinking of the case where a
method becomes obsolete, but is unused. In that case, why go through all the
hassle of deprecation, if nobody uses it anyway?
However, what does this mean for obsolete code that *is* used? Can we just go
ahead and remove the usages, and then remove the code without deprecation? That
seems to be the logical consequence.
The result is a much tighter timeline from soft deprecation to removal, reducing
the amount of deprecated code we have to drag along and keep functional. This is
would be helpful particularly when code was refactored to remove undesirable
dependencies, since the dependency will not actually go away until the
deprecated code has been removed.
So, if we put in the work to remove usages, can we skip the deprecation process?
After all, if the code is truly unused, this would not do any harm, right? And
being able to make breaking changes without the need to wait a year for them to
become effective would greatly improve the speed at which we can modernize the
code base.
However, even skipping soft deprecation and going directly to hard deprecation
of the construction of the Revision class raised concerns, see for instance
<https://www.mail-archive.com/wikitech-l@lists.wikimedia.org/msg92871.html>.
The key concern is that we can only know about usages in repositories in our
"ecosystem", a concept introduced into the policy by the section quoted above. I
will go into the implications of this further below. But first, let me propose a
change to the policy, to clarify when deprecation is or is not needed.
I propose that the policy should read:
Obsolete code MAY be removed without deprecation if it is unused (or
appropriately gated) by any code in the MediaWiki ecosystem. Such
removal must be recorded in the release notes as a breaking change
without deprecation, and must be announced on the appropriate
mailing lists.
Obsolete code that is still used within the ecosystem MAY be
removed if it has been emitting deprecation warnings in AT LEAST
one major version release, and a best effort has been made to
remove any remaining usages in the MediaWiki ecosystem. Obsolete
code SHOULD be removed when it has been emitting deprecation
warnings for two releases, even if it is still used.
And further:
The person, team, or organization that deprecates code SHOULD
drive the removal of usages in a timely manner. For code not under
the control of this person, team, or organization, appropriate
changes SHOULD be proposed to the maintainers, and guidance SHOULD
be provided when needed.
Compared to the old process, this puts more focus on removing usages of obsolete
code. Previously, we'd often just wait and hope that usages of deprecated
methods would vanish eventually. Which may take a long time, we still have code
in MediaWiki that was deprecated in 1.24. Of course, every now and then someone
fixes a bunch of usages of deprecated code, but this is a sporadic occurrence,
not designed into the process.
With the change I am proposing, whoever deprecates a function also commits to
removing usages of it asap. For extension developers, this means that they will
get patches and support, but they may see their code broken if they do not
follow up.
Now, my proposal hinges on the idea that we somehow know all relevant code that
needs fixing. How can that work?
When TechCom introduced the idea of the "MediaWiki ecosystem" into the policy,
our reasoning was that we want to support primarily extension developers who
contribute their extensions back to the ecosystem, by making them available to
the public. We found it fair to say that if people develop extensions solely for
their own use, it is up to them to read the release notes. We do not need to go
out of our way to protect them from changes to the code base.
Effectively, with the proposed change to the policy, maintainers of public
extensions will get more support keeping their extensions compatible, while
maintainers of private extensions will receive less consideration.
It seems desirable and fair to me to allow for "fast track" removal of obsolete
code, but only if we create a clear process for making an extensions "official".
How exactly would an extension developer make sure that we know their extension,
and consider it part of the ecosystem? In practice, "known code" is code
accessible via codesearch[5]. But how does one get an extension into the
codesearch index? There is currently no clear process for this.
Ideally, it would be sufficient to:
* create a page on mediawiki.org using the {{Extension}} infobox,
* setting the status to "stable" (and maybe "beta"),
* and linking to a public git repository.
It should be simple enough to create a script that feeds these repos into
codesearch. A quick look at Category:Extensions_by_status category tells me that
there are about a thousand such extensions.
So, my question to you is: do you support the change I am proposing to the
policy? If not, why not? And if you do, why do you think it's helpful?
-- daniel
PS: This proposal has not yet been vetted with TechCom, it's just my personal
take. It will become an RFC if needed. This is intended to start a conversation.
[1] https://www.mediawiki.org/wiki/Stable_interface_policy
[2] https://www.mediawiki.org/wiki/Topic:Vrwr9aloe6y1bi2v
[3] https://phabricator.wikimedia.org/T193613
[4] https://phabricator.wikimedia.org/T255803
[5] https://codesearch.wmcloud.org/search/
--
Daniel Kinzler
Principal Software Engineer, Core Platform
Wikimedia Foundation
The Search Platform Team
<https://www.mediawiki.org/wiki/Wikimedia_Search_Platform> usually holds
office hours the first Wednesday of each month. Come talk to us about
anything related to Wikimedia search, Wikidata Query Service, Wikimedia
Commons Query Service, etc.!
Feel free to add your items to the Etherpad Agenda for the next meeting.
Details for our next meeting:
Date: Wednesday, November 4th, 2020
Time: 16:00-17:00 GMT / 08:00-09:00 PST / 11:00-12:00 EST / 17:00-18:00 CET
Etherpad: https://etherpad.wikimedia.org/p/Search_Platform_Office_Hours
Google Meet link: https://meet.google.com/vyc-jvgq-dww
Join by phone in the US: +1 786-701-6904 PIN: 262 122 849#
Hope to talk to you in a week!
—Trey
Trey Jones
Sr. Computational Linguist, Search Platform
Wikimedia Foundation
UTC-4 / EDT
I maintain spi-tools.js <https://en.wikipedia.org/wiki/User:RoySmith/spi-tools.js>. The source is in github. At the moment, my "release process" (if you could call it that) is to edit
User:RoySmith/spi-tools.js and copy-paste the new version. This works, but it's clunky. Is there some pre-existing tool for this?
I could build some little tool to to do this, but if something already exists, no need to reinvent the wheel.
Hi Community Metrics team,
This is your automatic monthly Phabricator statistics mail.
Accounts created in (2020-10): 416
Active Maniphest users (any activity) in (2020-10): 1158
Task authors in (2020-10): 627
Users who have closed tasks in (2020-10): 320
Projects which had at least one task moved from one column to another on
their workboard in (2020-10): 324
Tasks created in (2020-10): 2688
Tasks closed in (2020-10): 2393
Open and stalled tasks in total: 45983
* Only open tasks in total: 45034
* Only stalled tasks in total: 949
Median age in days of open tasks by priority:
Unbreak now: 9
Needs Triage: 593
High: 908
Normal: 1314
Low: 1880
Lowest: 1921
(How long tasks have been open, not how long they have had that priority)
Active Differential users (any activity) in (2020-10): 7
To see the names of the most active task authors:
* Go to https://wikimedia.biterg.io/
* Choose "Phabricator > Overview" from the top bar
* Adjust the time frame in the upper right corner to your needs
* See the author names in the "Submitters" panel
TODO: Numbers which refer to closed tasks might not be correct, as
described in https://phabricator.wikimedia.org/T1003 .
Yours sincerely,
Fab Rick Aytor
(via community_metrics.sh on phab1001 at Sun 01 Nov 2020 12:00:16 AM UTC)