Talk:Stable interface policy/Archive 2/Flow export

Why not a part of the existing deprecation policy?

See More

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

What's the advantage of having a separate policy for this? Why not integrate the new stuff into the existing deprecation policy? Legoktm (talk) 07:29, 23 September 2019 (UTC)

Because it's long, and defining what's stable is different from defining how to change stable things. The primary audience for the deprecation policy are core developers, while the primary audience for the stable interface policy are extension developers.

I'm not totally opposed to having a single policy, but I think it's less clear. And RFC is needed for adoption in any case. DKinzler (WMF) (talk) 09:30, 23 September 2019 (UTC)

If we only have one policy, I think it should be called "Stable Interface Policy", and the deprecation process would be part of that.

Because, as a new extension developer, "stable interface policy" sounds like something I should look at (I want to use stable interfaces), but "deprecation policy" doesn't sound so interesting (I don't want to deprecate anything). DKinzler (WMF) (talk) 09:35, 23 September 2019 (UTC)

I agree we should not be enacting a new policy. It is a new RFC for sure, but its outcome should be to revise the deprecation policy including possibly a rename of it.

The main part I currently find difficult in reviewing this draft is that it is unclear what is meant to be "new" or "different" from what we have. Perhaps we can update the draft to be a complete version of the policy, with the task outlining a (short) summary what what we intend to add or change (e.g. the effective difference). Krinkle (talk) 18:47, 9 October 2019 (UTC)

So, which do you prefer - an deprecation policy with a section on stable interfaces, or a stable interface policy with a section on deprecation procedures? DKinzler (WMF) (talk) 19:41, 9 October 2019 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Legacy functions that are implicitly public due to not having visibility modifiers are not considered public by this policy

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

Unfortunately years ago people went through and added "public" to most if not all of these. Same for fields declared with var rather than an explicit visibility modifier. Anomie (talk) 16:40, 10 October 2019 (UTC)

Yes. I don't think there is an easy way to fix this. Perhaps we could add something like: fields and functions that appear to have been marked as public without a specific need for public access may be changed to not be public, if they have no known callers.

I'd like this for obvious reasons, but it seems a bit like a cop-out... "we guarantee this interface is stable, unless it's inconvenient"... DKinzler (WMF) (talk) 11:23, 18 December 2019 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Some thoughts about simplifying annotations

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

Make it so that interfaces and protected methods are stable by default. I think this is more intuitive and easier to remember. It also reduces the need for annotations for restoring stability as opposed to removing it. I'd assume extensible classes are so few, that it won't create much extra work annotating the unstable protected methods. Similarly I expect most interfaces to be stable by default.

With regards to inheritance, I would prefer being super explicit by using a combination of @extensible (class level) + @overridable (method level). This would set a clear tone that inheritance is very exceptional and only allowed in very specific places indicated by the developers. This way it is also kept separate from stability for callers.

@experimental is so close to @unstable, that I would merge these two.

Assuming we keep the "exception" for constructors (unstable by default), we still need one annotation for restoring stability. We can either use @newable (class level) or @stable (method level). I would choose the one which is more likely to be shown by IDE (or in the generated documentation) when writing code. Nikerabbit (talk) 12:40, 19 December 2019 (UTC)

Make it so that interfaces and protected methods are stable by default.

I can make protected methods of extensible classes "stable for calling" per default. I'll changed that in the draft. However, all methods should only be considered "stable for overriding" when explicitly marked as such, I think.

Similar for interfaces: they define public methods, which are "stable for calling" per default. However, we don't want extensions to assume that they can safely implement interfaces defined by core - the problems arising from this practice were what motivated this policy in the first place, T193613. This is contrary to the text book understanding of what interfaces are for, but from the discussions we had about T193613, it seems this is what we want: the preferred mechanism is extending base classes, implementing interfaces directly should be considered unsafe unless documented to be safe.

I would prefer being super explicit by using a combination of @extensible (class level) + @overridable (method level).

Yes, I agree. I tried to capture this in the description of the annotations. Do you have a suggestion for making this more explicit?

@experimental is so close to @unstable, that I would merge these two.

I only included both because both seem to be present in our code base already. But there are only very few instances of @experimental, we can probably ignore them. I'll update.

Assuming we keep the "exception" for constructors (unstable by default), we still need one annotation for restoring stability. We can either use @newable (class level) or @stable (method level).

I think both should be done explicitly: classes that are newable or stable for subclassing should have a constructor that is marked as stable for calling.

DKinzler (WMF) (talk) 09:18, 7 January 2020 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Exception for things that are not called by public code

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

The introduction of the current deprecation policy was a significant concession to third party interests compared to the previous defacto situation, and I think this proposal may take things even further in their favour, at the expense of the convenience of core developers. Hooks (and pretty much all other extension interfaces) expose kitchen sink classes, often with methods that give access to pretty much the whole of MediaWiki (RequestContext etc.), and thus would seem to require stability of those classes.

I would propose tipping the balance slightly by permitting removal without deprecation in git master, and any other breaking change to stable interfaces, in cases where the change can be shown to have no impact on extensions in the public MediaWiki ecosystem as exposed by CodeSearch. I think this would just require a change to the "removal without deprecation" section of this policy.

This idea was discussed in the context of the introduction of the current deprecation policy, and the consensus at the time seemed to be that it is worthwhile to protect the interests of developers of private extensions. I think this is a good opportunity to reconsider that decision. Tim Starling (talk) 04:47, 10 January 2020 (UTC)

I'd be very happy to see this change (as one of the people who helps deprecate and remove a lot of code). Jdforrester (WMF) (talk) 17:15, 10 January 2020 (UTC)

This makes sense to me. Going through the deprecation process for things that are probably unused anyway is cumbersome, especially since it's for the potential benefit of people who are not contributing back to the ecosystem. I'll make the change as proposed. DKinzler (WMF) (talk) 11:20, 14 January 2020 (UTC)

One question that has come up wither we should count extensions that are on mediawiki.org and point to a public repo in the info box should be counted as "part of the ecosystem". I think it would be fair to do that, but surveying them by hand is impractical. We'd have to find a way to include them in code search.

DKinzler (WMF) (talk) 13:35, 15 January 2020 (UTC)

I think we can respond re-actively; if a repo isn't covered by code search, a change like this happens, and someone complains, we'll add the repo to code search so it'll be fixed in future. Jdforrester (WMF) (talk) 18:32, 15 January 2020 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Doxygen?

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

Of the new annotations proposed here, it looks like

• "@newable" should be straightforward to add an alias for. "@unstable" as a stand-alone thing too.
• "@internal" is used for something else in Doxygen, but we could override it if we want.
• "@stable for X" and "@unstable for X" seem like they might be difficult to have Doxygen produce sensible output for. You can only alias the "@stable" and "@unstable" part and have to deal with the "for X" part as trailing text that you can't actually do anything with. Anomie (talk) 18:35, 11 February 2020 (UTC)

My idea is indeed to make Doxygen understand "@stable", and treat anything after it as free text, governed only by convention. We do the same for "@deprecated" already, right?

The alternative would be to use "@stable_for_calling", "@stable_for_subclassing", etc. Or come up with distinct adjectives for the different kinds of stability. That's what I had been proposing initially, but it seemed arbitrary and confusing. DKinzler (WMF) (talk) 12:03, 24 February 2020 (UTC)

Following @deprecated, it would render something like

Stable:

for calling

I guess the question is whether that's acceptable output or not.

For the record, Doxygen aliases can match /^[a-z_A-Z][a-z_A-Z0-9]*$/, and they can have parameters in braces so we could have something like "@stable{calling and subclassing} Some optional explanatory text here" render like

Stable: calling and subclassing

Some optional explanatory text here

The alias for that would be something like stable{1}=\par \"Stable: \1\"".

You still can't do too much with the parameters, it mostly just gives you a little extra flexibility since you can put stuff after the value. Anomie (talk) 13:43, 24 February 2020 (UTC)

Oh, I didn't know about parameters! Thanks!

Hm... parameters produce the nicer output, but seem more clunky to read and write in the source. As someone who never reads the doxygen output anyway, my preference would be to not use arguments, but just plain text. But I don't have strong feelings either way. DKinzler (WMF) (talk) 16:56, 24 February 2020 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Deprecation of Hooks

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

The policy states ''"Deprecation of hooks MUST be mentioned in docs/hooks.txt."'' which is obsolete now. It should be replaced by ''"Deprecation of hooks MUST be declared in the DeprecatedHooks class."'' DKinzler (WMF) (talk) 11:29, 17 July 2020 (UTC)

Sure - +1 from me. Does this need an official discussion on phab or should we just leave this open for a few days before making that change? DannyS712 (talk) 03:37, 18 July 2020 (UTC)

I suggest to leave it open at least until next Thursday, so TechCom can have a look. DKinzler (WMF) (talk) 08:30, 18 July 2020 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Confusion about the timeline for removing deprecated code

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

The 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.

So this seems to imply that code that starts to emit a deprecation warning in version X can only be removed in version Y. In terms of master development, this means that code can only be removed if it has started to emit deprecation warnings before the last release branch was cut (and waiting for two such cuts is recommended). This effectively recommends that code be kept in the hard deprecated state for at least half a year, with a preference for a full year. 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.

It is unclear whether this only applies to code that had already been unused before becoming obsolete, making deprecation unnecessary. Or if it also means that after deprecation, obsolete code can be deleted as soon as all known usages have been removed. This would allow for a much tighter timeline for the removal of deprecated code: unwanted code can be removed from one release to another without any deprecation (in a release), if all usages have been removed.

I see no harm in the latter interpretation, if we are careful to actually catch and remove all usages. I believe this interpretation is desirable, since it allows for a much faster pace of change. However, it may come as a surprise to some, so we should clarify the wording.

Perhaps something like this:

Obsolete code MAY be removed without deprecation if it is unused (or appropriately gated) within the MediaWiki ecosystem, which is defined as all actively maintained code covered by the code search tool. 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, but removing usages of obsolete code SHOULD always be preferred. Code that has been emitting deprecation warnings SHOULD be removed as soon as possible, and MUST be removed if it has been emitting deprecation warnings for more than one major version release.

I believe this would be more clear. Thoughts? DKinzler (WMF) (talk) 10:33, 12 August 2020 (UTC)

Agree its clearer, and it clarifies the disagreement between the fact that it can be bypassed entirely, and the recommendation to wait.

Eg at https://gerrit.wikimedia.org/r/c/mediawiki/core/+/614027 @Legoktm: gave a -2 for removal of hard deprecated code that was only hard deprecated in 1.35, saying "please wait until at least 1.37 per 'It is RECOMMENDED to emit hard deprecation notices for at least two major MediaWiki versions'."

I wonder though, if its a good idea to say that it MUST be removed after more than one major version. Is there anything between SHOULD (for removal as soon as possible) and MUST than can be used? DannyS712 (talk) 10:37, 12 August 2020 (UTC)

> "Is there anything between SHOULD (for removal as soon as possible) and MUST than can be used?"

Not according to rfc:2119. But perhaps we could find something suitable in the vocabulary proposed by rfc:6919... DKinzler (WMF) (talk) 14:36, 12 August 2020 (UTC)

Perhaps "Code that has been emitting deprecations warnings SHOULD be removed as soon as possible, and developers WOULD PROBABLY want to prioritize removal of code that has been emitting deprecation warnings for more than one major version release."? "WOULD PROBABLY want to" could also be replaced with "OUGHT TO", both from rfc:6919 DannyS712 (talk) 05:02, 14 August 2020 (UTC)

I think we should keep in mind the purpose of such rules.

• If it is to be expected that people from the outer world are using public interfaces which were propagated for a longer period, the removal after deprecation message should take several years if it is not very expensive or blocking to maintain an old function name or redirect something in a cheap way.
• If it is unlikely that something is accessed by 3rd party and supposed for rather internal usage, it might be executed more quickly and even without announcement to the outer world.
• People using MW externally who are always catching the recent half year version should get a chance to see a message before updating next time, and prepare migration without sudden breakage.
• There is no need to force us to maintain a tight schedule if there is no advantage by substantial simplification of procedures. PerfektesChaos (talk) 12:36, 14 August 2020 (UTC)

Note that misunderstanding (example) (and violating) the deprecation policy can happen in areas where code review is not as thorough. Without recognizing this, code that's still in use (search) by 30 skins was removed (patch). The fix still has to be merged (patch).

Some form of training or a video might be helpful to avoid these mistakes. —Aron Man.🍂 edits🌾 05:21, 3 November 2020 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Use of traits

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

Please see phab:T263904, which I just filed, asking about the stability (or lack thereof) of traits in core. Traits are not currently mentioned in the policy. DannyS712 (talk) 04:40, 26 September 2020 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Deprecation on master while a release is being prepared

The policy currently states:

• Deprecations and removals SHOULD NOT be performed shortly before a release branch or between release candidates, to give extension authors time to fix any issues that may arise, and avoid broken snapshots of extensions.
• Deprecations and removals MUST first take place on the master branch. Deprecations and removals SHOULD NOT be backported to release branches or release candidates.

It seems like the first bullet point is redundant and misleading: we can still do deprecations on the master branch while release candidates are being prepared. We just shouldn't add deprecations to the branch that is going to be released. Since that is already covered by the wording in the second point, I think the first point should simply be removed. DKinzler (WMF) (talk) 18:10, 29 April 2021 (UTC)

Agreed on the point about "being prepared", but the main part should stay. It's really unhelpful to make large breaking changes (which deprecations are, in effect) a few days or hours before a branch is cut, and doing so just afterwards can make backports very hard. Jdforrester (WMF) (talk) 19:25, 29 April 2021 (UTC)

Should we be more specific about what "shortly" means? A week should do, right? We'd need some kind of official "pencils down" warning for this to work. DKinzler (WMF) (talk) 20:30, 3 May 2021 (UTC)

No, not just a week. I'd recommend a month before and after the branch point, generally. This isn't about Wikimedia staff fixing things (where a week's notice is very tight but might be OK), this is about the wider ecosystem, right? People might not even notice that their extension no longer passes CI for a week or two after the deprecation, let alone fix it. Jdforrester (WMF) (talk) 15:27, 4 May 2021 (UTC)

That would mean not making deprecations in two out of six months. That seems like a massive impediment.

Can't we just run CI for all of them? DKinzler (WMF) (talk) 15:47, 4 May 2021 (UTC)

No? Running >>US$1k worth of CI CPU time for every patch to MediaWiki core, and then doing something with that result, would be a massive change to our CI budget and expectations for developers. (If a patch in core causes a failure in an extension, how is that communicated? To whom? How do maintainers find out that they need to do something? How do core developers not end up deluged by false positive "failure" messages from the dozens of extensions that are broken already? Etc.)

Also, this is just documenting current expectations, it's not a change to the current reality, AIUI? Jdforrester (WMF) (talk) 19:48, 4 May 2021 (UTC)

Not doing deprecations for a month before and after a branch cut is definitely not current reality, and never has been as far as I can remember.

My suggestion was to run CI on all of them when doing the rc0 branch, not on every patch. My hope is that this would result in extension maintainers noticing and fixing issues before the actual release. DKinzler (WMF) (talk) 08:35, 5 May 2021 (UTC)

I mean, I often C-1 patches that would be disruptive, as do many of the usual crowd. I'd encourage you to consider doing the same, out of respect for the time of colleagues and particularly the Security team when making last-minute back-ports.

The wider suggestion is an interesting idea. You should pitch it to RelEng, though I imagine they'd want to defer such work until after the GitLab migration rather than implementing such a tool from scratch twice within a year. Jdforrester (WMF) (talk) 14:44, 5 May 2021 (UTC)

To clarify: I agree that we should not do backports shortly before a release. Deprecations and removals should not be backported at all. But doing a deprecation on master a week before or after the rc0 branch is cut seems fine to me. I'm not sure I understand the problem with that. Extensions authors still have a month to fix problems between rc0 and the actual release, right? Maybe I'm misunderstanding when and how extensions snapshots are made...

As to running CI for all extensions... it wouldn't be hard to write a script that pushes a DNM patch to every repo, right? And maybe even automatically file tickets if these patches fail to pass CI... DKinzler (WMF) (talk) 16:43, 5 May 2021 (UTC)

To clarify: I agree that we should not do backports shortly before a release. Deprecations and removals should not be backported at all. But doing a deprecation on master a week before or after the rc0 branch is cut seems fine to me. I'm not sure I understand the problem with that. Extensions authors still have a month to fix problems between rc0 and the actual release, right? Maybe I'm misunderstanding when and how extensions snapshots are made...

There are two sources of pain:

• People making big changes "just" after the branch is cut, before it's released. This pain mostly affects MediaWiki itself and deployed extensions.
• People making big changes "just" before the branch is cut. This pain mostly affects those extension developers who aren't pushing a patch every few hours.

Branches are cut from master at the same time or very shortly after the "final" alpha deployment branch is, for all ~1800 extensions and skins (not just the ~200 in Wikimedia production). After that, there's a period of manual testing for things that no-one cares about except in releases, like the installer, and a bunch of bugs are found and fixed. As with all Wikimedia development, those changes are made first to the master branch and then back-ported. We also backport major bug fixes that are discovered during the week of the deployment. The general guidance is that this post-cut process can take up to six weeks until rc.0 is cut, though in practice I'd not worry about it much beyond the first three–four. Naturally, LTS releases make for even more pressure to get things out of the door, and so rc.0 can unveil lots of bugs and need several follow-ups (as we found with the 1.35 release), but in general it's pretty free sailing after rc.0 is released.

For the first area of pain, large scale refactors or removals of code very frequently mean that these back-ports can't be easily made, or in some cases have to be re-written from scratch. In general the burden of this churn doesn't fall on the person that made the work by merging the refactor so swiftly, but on the bug fixer (or worse, someone like me just trying to help the release get out).

For the second area of pain, hard deprecations are, per long-standing development policy, effectively a breaking change for development (and for Wikimedia-deployed code), as they make CI fail. If one were e.g. to hard-deprecate the User class a week before REL1_37 were branched, hundreds of extensions would immediately be broken for development, and either their owners would find out a month or two later when they next pushed a patch, or (more frequently) helpers like me or tools like LibraryUpgrader would encounter it when fixing up the repo for other reasons.

I think this section should be split into statements about breaking changes and deprecations, and say different things about them, e.g.:

• Breaking changes and large or risky refactors SHOULD NOT be performed during the few weeks running up to a release being branched until the first release candidate is made, to make it easier to back-port bug fixes to release candidates.
• Hard deprecations SHOULD NOT be performed shortly before a release branch, to give extension authors time to fix any issues that may arise.
• Deprecations and removals MUST first take place on the master branch. Deprecations and removals SHOULD NOT be backported to release branches after the first release candidate is made.

Would that work? Jdforrester (WMF) (talk) 17:31, 7 May 2021 (UTC)

Maybe I'm thinking about this wrong, but in my mind, the best time for extension developers to discover and fix issues is after the branch has been cut, so it's no longer a moving target. I assumed ExtensionDistributor will pick up any fixed made to the extension's snapshot branch. In my understanding, this would make sure that at the time of the release, the snapshot branches of extensions have also been fixed. To support this, CI should run against the extension when the branch is created.

As to not making major changes between the branching and the release of rc0: I think this is reasonable, but would need to be announced more clearly. Also, having at least a rough idea of the timing beforehand would allow teams to plan around this. DKinzler (WMF) (talk) 15:27, 2 June 2021 (UTC)

Removing obsolete unused behavior without delay

The policy currently states:

• Obsolete behavior MAY be removed right away if it appears to have never been used within the Wikimedia maintained code and the MediaWiki ecosystem (except in the repo that defines it), and seems unlikely to be used elsewhere.

This misses the point that code that has been in use only in the repo it is defined in, and perhaps in extensions maintained by the same entity, should allowed to be removed.

Perhaps this point should be rewritten as follows:

• Obsolete behavior MAY be removed right away if it appears to have never been used within the MediaWiki Ecosystem in a repository other than the one it is defined in. Even then, it MAY be removed right away if it has only been used in repositories maintained by the same entity. DKinzler (WMF) (talk) 18:15, 29 April 2021 (UTC)

Also, perhaps it would make sense to clarify how this provision interacts with another part of the policy, namely:

• If it is not reasonably possible for the deprecated code to emit deprecation warnings, hard deprecation can be applied by announcing the removal on wikitech-l in a timely manner.

Taken together, this means that certain breaking changes may only require an email to wikitech-l and a brief wait. This may be useful e.g. when it is desirable to change the return type of a method in a way that does not break any known callers: there is no way to deprecate a return type, so if nothing seems to rely on the old type, it's ok to change it after asking about concerns on the mailing list. DKinzler (WMF) (talk) 10:18, 30 June 2021 (UTC)

Removing @stable on soft deprecation

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

The policy seems to suggest or assume that being @stable and @deprecated are mutually exclusive. Some stability types explicitly state this (such as stable to call and stable to type), in others it seems to be implied (e.g. stable to extend: Only classes that are marked @stable to extend).

To make this clearer, I suggest adding a bullet point similar to the following to the section on soft deprecation:

• Soft deprecated code SHOULD NOT be marked stable. Any @stable annotations should be removed at the same time that a @deprecated annotation is added.

And maybe also this to the section on hard deprecation:

• Hard deprecated code MUST NOT be marked stable. Lucas Werkmeister (WMDE) (talk) 16:06, 2 June 2021 (UTC)

I agree that they are mutually exclusive and that @stable should be removed upon deprecation. If this gets added to the official policy, it might be worth having a codesniffer warning for both @stable and @deprecated in the same doc block. DannyS712 (talk) 16:41, 2 June 2021 (UTC)

I agree that we should remove them on deprecation, but perhaps in our @deprecated tags we should explicitly say that it used to be stable to extend/etc.? Jdforrester (WMF) (talk) 20:06, 7 June 2021 (UTC)

Hm, I just noticed this in Stable interface policy § Add guarantees:

The @stable annotations can be followed by a Deprecated since segment to indicate that a particular use of the class or method is currently deprecated. This can be used to indicate that extensions should no longer subclass, but may still call public methods. This guruantee may then be removed in the next release. Note that there is currently no hard-deprecation for the removal of stability guarantees.

/**
 * @stable to extend Deprecated since 1.35
 */
class Foo {
    /* … */
}

Not sure what that means for this proposal… Lucas Werkmeister (WMDE) (talk) 09:03, 8 June 2021 (UTC)

Hmm. Perhaps @DKinzler (WMF) can suggest how he saw this working? Jdforrester (WMF) (talk) 17:25, 10 June 2021 (UTC)

I think it should work as follows:

When the intent is to remove, then `@stable` should just be replaced by `@deprecated`. No code should use it.

If the intend is to keep but make internal, `@stable` can have a "deprecated since" qualifier added. This prevents internal use of the affected code from being flagged as deprecated by IDEs and other tooling, while giving extensions authors at least some warning. It's basically "deprecated for public use but ok to use internally". DKinzler (WMF) (talk) 11:15, 11 June 2021 (UTC)

Thanks, that seems reasonable. I've tweaked the wording; hope this is correct and uncontroversial? Jdforrester (WMF) (talk) 17:15, 11 June 2021 (UTC)

Yes, thank you! DKinzler (WMF) (talk) 10:04, 30 June 2021 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Deprecation of code and LTS releases

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

The policy of "removing deprecated code after 1 major release (or 2)" has a really MAJOR problem. It has to do with extensions. With extensions that are not used by MediaWiki (and maybe not used by a lot of people), the extensions may only get updated during LTS revisions. When every single major release that is not a LTS release can have breaking deprecated code, when a programmer comes along and tries to bring old extensions up to date (usable with the new LTS), there is no central "checklist" (or anything) indicating what exactly has changed. Even a list would be helpful. Then at least somebody can create a utility (maintenance file) that can be run against an extension to determine what things need to be updated to be compliant with the new LTS. Specifically, I am talking about third party extensions that run in 1.31, but do not run in 1.36 (for a variety of reasons). Some of which just kind of scrapped by when going from 1.29 (or less) to 1.31.

The whole point of a LTS is so that a company (or third party extension developer) does not need to worry about all of the little changes that happen between LTS version and can just focus on the LTS versions. But it does not seem as though the development team at MediaWiki is paying attention at all to people trying to move from 1.31 LTS to 1.36 LTS. Proactive programming (talk) 20:42, 13 June 2021 (UTC)

There needs to be a maintenance function that can at least point out to a third party developer which functions calls (or hooks) are deprecated. Something like "extensionLintChecker.php" and "skinLintChecker.php" for skins. Something that will produce a report saying "File:myextension.php" is using "Deprecated function "nogo()". Replaced by "yesnow1() and againnow()" (or something to point the developer in the right direction to fixing the extension. Proactive programming (talk) 20:48, 13 June 2021 (UTC)

It's probably not what you're looking for, but each version's release notes includes a list of deprecated (and removed) code features. 「ディノ奴千？！」^{☎ Dinoguy1000} 23:44, 13 June 2021 (UTC)

Also most extensions are checked via https://codesearch.wmcloud.org/search/ in general, so this can only rly happen to extensions that have not been added to that. That service is managed https://gerrit.wikimedia.org/g/labs/codesearch and you can also file a phabricator ticket to get extensions added to it. —TheDJ (Not WMF) (talk • contribs) 08:51, 14 June 2021 (UTC)

"LTS" is a commitment about MediaWiki itself, including the skins and extensions shipped in the "tarball". It's not a general commitment for all Wikimedia-authored extensions, and certainly not by the hundreds of independent extension authors.

If you're using an extension that doesn't bother to keep current with MediaWiki except for LTSes, I'd very strongly counsel you to stop using it and find an alternative. Jdforrester (WMF) (talk) 16:41, 14 June 2021 (UTC)

"Long Term Support" means WMF provides bug fixes and security fixes for two years. It provides no guarantees about backwards compatibility, and it never was intended to do that.

Extension developers who choose to only update their extension for LTS releases may see their extension not working with intermediate releases. If that was not the case, we couldn't make any "major" releases between LTS releases. The very definition of a major release is that it breaks backwards compatibility - otherwise, it would be a minor release. DKinzler (WMF) (talk) 10:12, 30 June 2021 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Documenting widening of parameter types

Widening the types of parameters is allowed by the stable interface policy, as it it does not break any callers. Example:

- public function addLink( Title $title, $id = null ) {..}
+ public function addLink( LinkTarget $link, $id = null ) {..}

This can pose an issue for developers of extensions and skins, who want to maintain compatibility for multiple versions of MediaWiki core: when refactoring or writing new code, we may accidentally use LinkTarget (with the above example) even though it will not work with older versions of MediaWiki. Detecting these issues is difficult due to low(er) testing with older versions of MediaWiki compared to the latest version.

For other things, that may be backwards incompatible, we can check the @since tags for the relevant classes/methods/constants/etc. For this kind of compatibility issue there is currently no standard way to check other than reading the source of each supported MediaWiki core version.

I propose that we mention these kind of type changes in the parameter documentation. IDEs like PhpStorm will show this documentation when writing code, which makes it easier to avoid introducing these kind of breakages accidentally. Nikerabbit (talk) 11:19, 14 October 2021 (UTC)

Deprecation process and translatewiki

A recent deprecation following this process caused problems in the translatewiki extension (context https://phabricator.wikimedia.org/T310017#8236113)

The guide currently says: > Developers or teams deprecating code SHOULD actively support removal of usages in code in the MediaWiki ecosystem, especially in popular extensions. This includes making maintainers aware of the deprecation as well as creating or reviewing patches removing usages.

"popular extensions" is quite a vague term here, as it's not clear what's popular. Codesearch currently shows results for many extension/skins that are unmaintained or pinned to older MediaWiki versions, so its often hard to identify which skins.

"active" is also vague here. In the case of T310017 work was still ongoing to support removal of usages but a translatewiki deployment happened somewhere in the middle of that process.

Questions:

• Should TranslateWiki installed extensions/skins be treated as "Wikimedia deployed" code and block hard deprecations?
• If not should codesearch provide a tab in addition to "Wikimedia deployed" e.g. "Translatewiki deployed"
• Could we provide more guidance about what we class as popular extensions/skins with some kind of criteria e.g. used on X site, Y+ downloads? Jdlrobson (talk) 15:42, 14 September 2022 (UTC)

Should TranslateWiki installed extensions/skins be treated as "Wikimedia deployed" code and block hard deprecations?

No, I don't think so. Though we're fans of TWN and fund them, as well as using them, they aren't part of our ecosystem (and shouldn't be forced to follow our processes and all the rest).

If not should codesearch provide a tab in addition to "Wikimedia deployed" e.g. "Translatewiki deployed"

Sure, that's pretty easy to add if that would be useful. Jdforrester (WMF) (talk) 07:58, 16 September 2022 (UTC)

Re: popular extensions, we used to have this dashboard for things in ExtensionDistributor/Gerrit, but it's timing out right now. WikiApiary has been unreliable for years, but that used to be another good source of data.

SMW is a weird spot in which it is an incredibly popular extension, but because development is on GitHub (requires use of proprietary software) and it has no code of conduct (and historically has been toxic/unfriendly) I would not even suggest recommending or asking people to file tickets there. I think that is entirely on the SMW maintainers/community to fix.

Overall I do think TWN is a good bellwether for how people use MediaWiki in the wild, but I don't think it should be codified in policy. Legoktm (talk) 23:46, 17 September 2022 (UTC)

Deprecating config settings

Since 1.39, the installer will warn about the use of deprecated settings. But this only works as long as the declaration of the config setting is kept. Since people often upgrade from old versions after many years, it seems useful to keep the declaration around for a long time.

The old setting can however be ignored. The deprecation warning can just say that the setting no longer works. We just need to declaration in place so the installer tells the user.

Maybe instead of using the "deprecated" flag in the schema, we should have an "obsolete" flag for settings that are no longer supported? We could keep them indefinitly. Duesentrieb ⇌ 18:18, 3 October 2022 (UTC)

This is a great idea, though it seems like we could do both? Warn on deprecation and for obsolete settings? Legoktm (talk) 02:34, 4 October 2022 (UTC)

Yes, of course, it should do both! But deprecated settings would still work, while obsolete settings would be defunct. The idea here is to make the distinction explicit, and allow backwards compatibility code for old settings to be removed without breaking old installs without explanation. Being able to declare settings as obsolete will allow us to break old installs WITH explanation ;) DKinzler (WMF) (talk) 19:27, 4 October 2022 (UTC)

(I just realized I have been editing here with two accounts - full disclosure: User:Duesentrieb is also me, that's my private account) DKinzler (WMF) (talk) 19:29, 4 October 2022 (UTC)

I made a patch that introduces the an "obsolete" marker into MainConfigSchema, and uses it in the updater and structure tests:

https://gerrit.wikimedia.org/r/c/mediawiki/core/+/838769 Duesentrieb ⇌ 11:10, 5 October 2022 (UTC)

@DKinzler (WMF), I agree with you on the "obsolete" flag. It will inform 3rd party users to cleanup their LocalSettings.php and remove what is no longer needed for their installs (or update to the new ways of doing things).

Since we can't know what outside user LocalSettings.php looks like, this a good strategy to keep things clean on their own side too, which after sometime, cleaning up these configs from core would be safer.

But the thing is, how long do we want to keep the deprecated configs? 2, 5 or 10 years before completely removing? X-Savitar (talk) 11:45, 5 October 2022 (UTC)

With this mechanism in place, we could start to remove backwards compat code for deprecated settings more agressively, after or two releases, like other deprecated code. The declaration of the obsolete setting would need to be kept for as long as we support upgrading from a revision where the setting was not deprecated (but not before two LTS releases from now, because older versions don't emit warnings).

I.e. if in 1.44 we drop support for upgrading from 1.35, we can remove all obsolete config that has been deprecated since at least 1.35.

This would be safe since when upgrading to 1.44 from a version > 1.35, you'd see the warnings. And when upgrading from an older version, you'd have to upgrade to a version < 1.44 first, so you'd also see the warnings.

Since we currently guarantee updates across two LTS releases, and we do an LTS release every other year, this would come to four to five years from deprecation to full removal. The b/c code could already be removed after about a year, though, moving the seeting from deprecated to obsolete. DKinzler (WMF) (talk) 18:44, 5 October 2022 (UTC)

Something that more interactively helps sysadmins when upgrading to know what config they need to update/remove would be really great, rather than hoping that people carefully read the upgrade notes. Great plan. Jdforrester (WMF) (talk) 15:51, 6 October 2022 (UTC)

@Jdforrester (WMF), you captured it very well and I like how you put it. In this case, we're guiding the customer/end-users on how to configure their wikis and what to remove which is no longer needed for/after upgrades.

I think a lot of sysadmins will be happy to see this feature (as here we're putting MW users again on the front line) and it'll make their life a whole lot easier when managing those giant LocalSettings.php files :) DAlangi (WMF) (talk) 21:20, 7 October 2022 (UTC)

removing class aliases

Class aliases are basically deprecated names for classes. I think that the deprecation process should apply for them, so it is clear when we can remove them. But there is no good way to emit deprecation warnings... Duesentrieb ⇌ 10:20, 16 January 2023 (UTC)

For things that can't be warned about, we generally do a 'best efforts' approach, looking through codebase through Code Search and determining how likely it is that people will be disrupted (and writing patches to migrate where the codebases are current enough to pass CI). Not sure that this needs formalisation? Jdforrester (WMF) (talk) 01:15, 17 January 2023 (UTC)

Suggestion: Change author and user terminology

While working on a frontend equivalent of this policy, the names "provider" and "consumer" were proposed. In this document we currently have "author" and "user" to mean the same.

These words seem overloaded given an "author" could mean many things - such as editing documentation, editing wiki pages. A "user" could be interpreted as a user of the code.

How about we change all instances of "author" to "provider" and all instances of "user" to "consumer" ? Jdlrobson (talk) 16:55, 9 August 2023 (UTC)

These words seem overloaded

This document is addressed to a software development context. Do you think there is ambiguity in this context for who the author of a code interface is, or who the user of a code interface is?

In your experience browsing GitHub issue trackers and npm READMEs, do you find that people don't often use and understand terms like "author" and "user", or that these caused confusion? Perhaps an alternate set of terms is more often there that we could borrow from?

If we remove context from the equation, I believe it would be very challenging to find a term that is well known (i.e. not too novel, or unknown to ESLs), easily understood, and ambigious regardless of context.

The word "consumer" seems certainly ambigious. Like "user", a "customer" often refers the end-user (possibly more often?). In my own experience, I find developers of open source software more often refer to themselves as "users" than as "consumers". (Most often would be "developer", but I mean cases where another term is used to disambiguate.) The term "consumer" might be a bit too corporate-y for FLOSS culture? Businesses and commerical enterprises refer to their users as customers.

Companies also tend to think of, and present, themselves as "provider" when they create software or services. This too carries a similar ambiguity. E.g. software consultancies that build WP or MW plugins, WordPress and MediaWiki hosting providers, companies like BlueSpice. I imagine most every developer working as user of MediaWiki core to build an extension, is providing something to someone. Even if merely as hoster of your own wiki with a custom extension, you'd be the site/content provider building on MW software. If I drop "Who is your provider?" in an unspecified technology-adjacent context, I think one tends to think first of web hosting, ISP, and telecom companies; Not easily would I think of the author of one of our npm dependencies, from whom I use the stable interface.

I'm not arguing that "provider" is unclear, but I do think, if we ignore the document context, that it is certainly ambigious. I feel the term "provider" also feels a bit less personal and human than an "author".

Note that we use term author a fair bit in our technical writing when we talk about ourselves as the authors (or "maintainers") of software, including AUTHORS.txt attribution, Git commit authors, author credits from extension.json for Special:Version, and more in search. Krinkle (talk) 23:28, 9 August 2023 (UTC)

Hard deprecation, release notes requirements

For soft deprecation we say:

"he deprecation MUST be mentioned in the relevant RELEASE-NOTES"

There is no requirement for hard deprecation but @Jdforrester (WMF) pointed out in https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1081276 we often update RELEASE NOTES to emit deprecation warnings.

I propose we add the following text to the hard deprecation section:

"When transitioning from a soft to hard deprecation, the RELEASE_NOTES must be updated to reflect the function now emits deprecation warnings." 198.27.180.35 (talk) 17:48, 30 October 2024 (UTC)

I'd probably recommend instead:

When upgrading a "soft" deprecation to also start emitting deprecation warnings in a different release to the original deprecation, the RELEASE_NOTES file SHOULD be updated to reflect this.

There are circumstances where it's not strictly needed, and it's only needed if the original deprecation was in a previous release. Jdforrester (WMF) (talk) 19:38, 30 October 2024 (UTC)