Apologies for speaking out of turn - I am not a developer but a user and one who might also have codes that might break subtly. Allow me to make a suggestion: consider changing the name of the top-level namespace from `skimage` to `scimage`. Such a name change would mean codes using `import skimage` would not break, but the package could be deprecated and eventually abandoned. This would make the new API and functionality be "opt-in", and so a deliberate act. It would be nearly painless, but is also a clear change that the downstream user would have to do. That is, if they discover a subtle bug in their code relate to these changes, git bisect could show them that it happened when they switched from `skimage` to `scimage` and so encourage them go re-read the FAQ and release notes. Since `scimage` is still short for "scikit-image", nothing else needs rebranding. You might even say (tongue-in-cheek, of course), "we decided to spell science with a 'c'". Feel free to ignore, Thanks for considering, Cheers, On Mon, Jul 19, 2021 at 8:21 PM Juan Nunez-Iglesias <jni@fastmail.com> wrote:
Hi Stéfan, Matthew,
Thanks Matthew for weighing in. Stéfan, no worries about having second thoughts — the purpose of the SKIP process is to account for these! But, my responses below — I’m still in favour of the SKIP.
There are two main concerns: breaking the Hinsen rule, and supporting users through the transition. Regarding the 1st:
Perhaps we should reconsider biting the bullet and going through the slower, trusted deprecation process? It is true that we are short on person-hours to do the work, but if we estrange part of our user base increasing volunteer time will become even harder.
I think this is actually *counterproductive* in the context of the Konrad Hinsen rule: if we change slowly with a deprecation path of adding `preserve_range=False` whose default value migrates to True over two versions, then *you end up breaking the Hinsen rule*, just over a slightly longer timescale.
And you don’t get your compatibility layer — earlier versions of the library don’t have `preserve_range` so you can’t easily support the later version and the earlier version simultaneously.
In contrast, if we go with the 1.0 approach and bundle a large number of breaking API changes, the odds of breaking the Hinsen rule are much smaller: almost all skimage 0.x scripts will fail with skimage 1.0.
In my opinion, the Hinsen rule argues in favour of either adopting the SKIP, or going with the skimage1 approach (new package name). It absolutely does not argue in favour of the slow deprecation path: we’ve probably broken the Hinsen rule more than a few times with that approach. For example, when we switched some regionprops from xy to rc coordinates. Code that measured object orientation in 0.14 will yield different results in 0.18 with no warning. (There is warning in the intervening versions, but that doesn’t help users now.)
Regarding the transition:
How practical will that be - supporting both scikit-image versions <=0.18 and >=1.0, within the same library?
This one is bigger: currently, that’s expected to be more or less impossible, or extremely painful. The SKIP bets on most libraries/users making a clean transition. Indeed that didn’t work out well for Python 2/3, but I think this transition is easier by at least two orders of magnitude. The Python 2/3 transition required rebuilding all the libraries in PyPI, including, for compiled libraries, subtle issues with the ABI that I don’t understand to this day. The scikit-image transition will involve:
- find/replace for certain function/attribute names - adding a call to `rescale_to_float` (or similar) before some function calls - transposing images in some calls to `transform.warp`
I think these can be adequately addressed by a simple migration guide.
The added complication is downstream packages of downstream packages. If you have a “dependency diamond” where A depends on B and C, both of which depend on scikit-image, A is stuck on the minimal version that B and C depend on, which can dramatically slow down the transition. This was brought up by Mark during the API meetings. I will add an explicit note to the SKIP because it’s a very important point. Here again I think scikit-image’s job is two orders of magnitude easier than Python’s: to a first approximation, I think scikit-image is high-level enough that this situation will be quite rare, and certainly won’t propagate many levels up like it did with Python. I also hope that most people will not feel compelled to support 0.19 and 1.0 simultaneously, as people did with Python.
So, based on the above, in my opinion, the only candidates are:
- accept the SKIP - create a new library - do nothing
and of those three, the SKIP is the most attractive. The new library has even higher potential of fragmenting the community imho.
Having said this, I would definitely still entertain `skimage.v0.old_module`. Alex was most reluctant about this, and I totally understand his reluctance, but it does fix the simultaneous dependency thing. To me it’s still much better than the slow deprecation path.
Juan.
On 20 Jul 2021, at 3:20 am, Stefan van der Walt <stefanv@berkeley.edu> wrote:
Hi Juan,
Thank you for writing up the SKIP; you clearly put a lot of thought and effort into it.
As I read the SKIP, and then reflecting on Matthew's email, I again started feeling very uncomfortable with what we are proposing to do here. My gut feel has always been that the magical pinning solution is bound to cause trouble. I just can't shake that it is going to cause a lot of headaches and confusion.
More importantly, thinking about what Matthew said and then looking at the list of silent API changes, there really is only one issue we need to address: data conversion. All the other API changes can be handled through a slightly more laborious process.
The data conversion issue is thorny. I know for a fact that a bunch of my code will break with proposed skimage 1.0, because the assumption of 0-255 uint8 meaning 0-1 float is so deeply baked in. No matter how we handle it, it's going to be messy; but doing it silently, even if widely advertised, can be very disruptive.
Perhaps we should reconsider biting the bullet and going through the slower, trusted deprecation process? It is true that we are short on person-hours to do the work, but if we estrange part of our user base increasing volunteer time will become even harder.
I'm sorry; I know we've had these discussions over and over, and that it is frustrating to have someone come on board and then fall off again. I keep wanting to be OK with a more radical move, but I am just not that confident we can pull it off.
Best regards, Stéfan
On Sun, Jul 18, 2021, at 21:32, Juan Nunez-Iglesias wrote:
Dear skimagers,
We are aiming to release scikit-image 1.0 near the end of the year. We are, however, planning to make a number of breaking changes in the API that will affect downstream libraries. We have published a proposal for how we plan to do this at https://bit.ly/skip-3. The gist of it is:
- we'll release 0.19 in the coming weeks. - we'll release 0.20 immediately after, which will be exactly the same but with a warning to pin scikit-image to `<0.20` (for those that want to stay in 0.x land indefinitely) or `!=0.20.*` (for those that want to be "on the ball" when 1.0 is released and update their code as soon as possible). - we'll publish a transition guide along with 1.0rc0, and maintain 0.19.x with bug fixes for another year to give users time to transition.
The document describes alternative approaches ("change the wheels on the bus while still driving it" or "make a new bus with a new name") and why the core team ultimately chose to promote the current approach. Nonetheless, scikit-image is committed to being a community-led project, so we are still gathering feedback and can make substantive modifications to the plan going forward. Please don't hesitate to voice your concerns so we can make the best choice for our entire community going forward!
Thank you,
Juan.
scikit-image mailing list -- scikit-image@python.org To unsubscribe send an email to scikit-image-leave@python.org https://mail.python.org/mailman3/lists/scikit-image.python.org/ Member address: jni@fastmail.com
_______________________________________________ scikit-image mailing list -- scikit-image@python.org To unsubscribe send an email to scikit-image-leave@python.org https://mail.python.org/mailman3/lists/scikit-image.python.org/ Member address: matt.newville@gmail.com
-- --Matt Newville <newville at cars.uchicago.edu> 630-327-7411