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 _______________________________________________ Wikitech-l mailing list Wikitech-l(a)lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l

I'd like to see third party users, even those not on the mailing list, get advance notice in one release (say in the release notes) so that when the next release shows up with the deprecated code removed, they have had time to patch up any internal extensions and code they may have. I don't want to penalize third parties who may not publish their extensions because they think the code is not good enough for public consumption or because it is very specific to their company or workflow. I also don't want to encourage delays in updating, or the common practice of running very outdated versions of MediaWiki. Of course some folks will remain on LTS; that's what it's there for. But once a new release is out, we should want parties to be in a position to update to it immediately, at least as far as our processes go. A delay of two releases is nice but not necessary and honestly I'd just skip that altogether. Just my .02 €, Ariel On Fri, Aug 28, 2020 at 12:19 PM Daniel Kinzler &lt;dkinzler(a)wikimedia.org&gt; wrote: and where a just deprecation? right? modernize instance https://www.mail-archive.com/wikitech-l@lists.wikimedia.org/msg92871.html have commits they not code public while the _______________________________________________ Wikitech-l mailing list Wikitech-l(a)lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l

Hi Greg, thanks for your reply! Am 28.08.20 um 18:26 schrieb Greg Rundlett (freephile): Just a quick clarification: while the current policy only considers code to be part of the "ecosystem" if it's on gerrit, what I proposed in my mail would mean that the Extension could be hosted anywhere, as long as it is public, and has a page on mediawiki.org -- Daniel Kinzler Principal Software Engineer, Core Platform Wikimedia Foundation _______________________________________________ Wikitech-l mailing list Wikitech-l(a)lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l

I appreciate your argument, however, I think the deprecation policy will be used in good faith. Fast deprecations are really helpful for code that is not been used. If one expects that a feature is used in hidden code probably people will not depreciate it too fast, especially if there is a lot of visible code to refactor.

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.

Am 31.08.20 um 18:52 schrieb Arthur Smith: development Typically, people viewing a this with experimenting and the Yes, in development model ($wgDeveloperWarnings = true), deprecation warnings are visible. But very commonly, people don't actively work on this "hidden code" any more. They wrote it once, it's working, and they will not look at it again until it breaks. I'm not blaming them, that's what I do for "one off" code. If they are actively developing features, then sure. But then they are likely to read release notes, or tests against master. -- Daniel Kinzler Principal Software Engineer, Core Platform Wikimedia Foundation

Hmm, maybe we're talking past one another here? I'm assuming a developer of an extension who is interested in testing a new release - if we have a version that has things deprecated vs completely removed, that allows a quick check to see if the deprecated code affects them without going back into their own code (which may have been developed partly by somebody else so  just reading release notes wouldn't clue them in that there might be a problem).

A clear and straightforward policy for getting things "in" sounds great. However, this might encourage the addition of extensions that are ultimately abandoned and which themselves become a code maintenance burden. We should also consider our policy for getting things "out". This is often a more difficult issue.

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.

MediaWiki version before being removed. It is RECOMMENDED to emit hard deprecation notices for at least two major MediaWiki versions.