Topic on Talk:Stable interface policy

The confusion has hopefully be resolved by the amendment to the policy in January 2021.

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?

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?

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

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

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.

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.