Topic on Talk:Stable interface policy/Archive 2

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

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.