Add documentation for deprecation process in CONTRIBUTING.txt

[jni]

There is a discussion in #2220 about a new way to handle API breakage: when it is easy to detect, break without the usual 2-release deprecation cycle, and raise an informative ValueError on incorrect usage of the new API. (For 2 releases still? Or 1 year?)

It also turns out that our deprecation process is not documented anywhere, that I can tell. Therefore, it would be good to codify both our existing process, and the above alternative, in CONTRIBUTING.txt.

[stefanv]

I'm surprised we failed to do this before; thanks for noticing, @jni.

I am happy with either approach, over two releases.

[sciunto]

I found this comment from Juan very useful: #2228 (comment)

[JDWarner]

I'll keep playing the devil's advocate on this.

As a user of many packages but a developer on some, I'd much rather have hard breaks with informative messages telling me what changed and how to fix it than a million deprecation warnings which will be ignored. In the vast majority of cases the deprecations will keep being ignored; code will break now or later. Our current modus operandi is to warn people for a while and then do a hard break. Again, I think this is worse from a user standpoint than an immediate break with instructions on why/how to fix it.

There are API changes where keeping the old way around is appropriate. When we can't detect the change, or it involves moving or deleting an entire function for example. However, when we occasionally merge in the wrong choices, like when kwargs have *_x or *_y instead of a single iterable, the last thing we want to do is sit on it for another year or two.

Because when we delay, the docstring keeps teaching people to do it wrong. Yes, deprecations are being thrown - and ignored because it works the other way, and that's what the docs say. So we lead ever more people toward trouble when we pull the trigger on the change.

If it is possible to detect the old method of input and output an informative error message, I'd argue it is not only advisable but always better to fix the API immediately in such cases.

[soupault]

Thank you, Josh, for the detailed expression of your position.

I can't remember any "stable" project which uses no-deprecation approach, so shouldn't we.

At the beginning of my argument I'd like to draw a line between the "legacy code" (i.e. functions and algorithms presented in the code for >2yrs) and the features we add recently. These two must be considered differently in terms of review and deprecation processes. Well, at least as long as the fundamental concepts and agreements of the project hold (for example, how we represent images, how we handle channels, and how we structure the algorithms (segmentation, filtering, etc...)).

I don't mind at all to see the current 2yrs deprecation cycle for the primary part of the project.

As for the second half, I think an indicative example to reason on could be a set of functions related to wavelet denoising. If any of you isn't aware, we haven't released the pywavelets dependency and the functions relying on it yet, but there is already a good chunk of wavelet-related code in master. At the moment, our dear contributors are playing with and modifying different aspects of the already merged into master code. As long as none of us is an ultimate scientist and programmer in the field of image processing (excuse me for saying this on your belahves) and cannot predict, structure the API and schedule all the work from the beginning, I believe we must expect many new feedbacks and proposals on the implementation of the wavelet denoising algorithm once we release 0.13. And after the release... Do we actually need to drastically change the way people work with that part of the code immediately introducing 2yrs deprecation policy? I don't think so.

Let me be frank. The activity on the project is not that high, and things are getting older with each day passed, and I'm greatly concerned that we shouldn't slow down things even more. At least, at the moment.

I think that the deprecation cycle of 2 releases (== 2 years) is rational for some cases but, in general, is too long, and I'd propose to be flexible with deprecations (i.e. decide on each deprecation case by case). Reasonable compromise could be to have 2 releases per years, and to keep deprecation cycle as is (== 1yr in total). But, from my perspective, this is not the case with the current development activity.

To summarize:

• yes to deprecation;
• 2yrs deprecation for the most stable fragments of the package;
• case by case deprecation cycle in other cases with the mode at 1yr (1 release?);
• do write code, and do release! if we regularly offer new things, users will be happy to manage updates. ✍️

P.S. - Just for the reference. I has been watching pandas development quite closely for the last 3 yrs. They had a new release every ~5 months, they did a lot of hard breaks, but they deprecated quite much also (2-3 releases). Nobody of the people I know who use Python everyday was upset by that.

[sciunto]

The release frequency is only decided by us. We can release more often as needed and I think that our frequency is too low, also because we have bug fixes in master. I'm not well experienced in releasing large projects but I imagine that a too low frequency makes the step higher due to numerous and various small details to fix.

[jni]

@sciunto yes, you are not alone in thinking that we are too slow to push out releases. The problem, illustrated by the last release push, which lasted many months, is that we really don't have a streamlined process to make a release. That is something we have discussed but not moved on. The last time I spoke with @stefanv he was even toying with the idea of continuous releases (ie each merge on master is a new release). =)

[stefanv]

@sciunto Would it help if we set up a release schedule and got volunteers to take responsibility for each?

[stefanv]

Also, no comment on Pandas.

[stefanv]

Or, perhaps that API breakages cause difficulty for developers depending on their frequency, not on the number of releases you make.

[sciunto]

I opened a PR that (tries to) summarize this discussion #2422

[sciunto]

@stefanv I think that anything that helps to make releases more regular and more frequent is good. Better for motivation, user feedback, baby step evolution. It would also help a lot to teach the library to colleagues (eg we have features in master that is a pain to share just because they are not well experienced to install something unreleased). As we deviate from the original issue, I do not develop more the arguments here.