Hi all!

In August, I wrote to this list to discuss the when and how breaking changes can be made without deprecation. The proposal I made at the time was admittedly rather radical, but it lead of a good discussion and flushed out a number of pain points and interesting ideas. Based on this discussion and other feedback, I have drafted an update to the Stable Interface Policy. You can find it here:

User:DKinzler_(WMF)/Stable_interface_policy (diff)

The draft has entered the RFC process, and I intended to move it through swiftly, so it can be adopted soon. If you have any thoughts or feedback, please reply to this email, or put it on the phab task.

I would like to highlight a few of the changes that I am proposing:

• Define the idea of a MediaWiki "ecosystem", and state that extensions in this ecosystem should receive support in dealing with upcoming breaking changes. The ecosystem includes actively maintained extensions hosted by Wikimedia or listed by the MediaWiki Stakeholder Group.
  
• Clarify that removal without deprecation is only ok for code that has never been used elsewhere.
• Allow "hard deprecation by announcement" when it is not possible to emit deprecation warnings. This was previously stated as an exception from the deprecation policy, rather than a mode of deprecation.
• Clarify that individuals or teams who deprecate code commit to removing usages of that code asap at least in code maintained by Wikimedia, and should support 3rd parties in this removal from code in the ecosystem.
• Remove the recommendation that hard-deprecated code should be kept for two releases. This is replaced by a requirement to keep it for one release, and three months on master.
• Clarify that deprecation and removal of deprecated code should not be backported to release candidates, and should ideally happen right after a release, rather than shortly before a release.
  

The intent is to streamline the deprecation process, ensuring that deprecated code becomes unused quickly, without causing too much of a disturbance.

Besides this, the proposal contains a number of other additions and clarifications, as described on the phab ticket and visible in the diff.

I'm looking forward to hearing your thoughts and ideas!

Daniel Kinzler
Principal Software Engineer, Core Platform
Wikimedia Foundation