Hi Matt,

Thank you for emailing and not out of turn at all! Indeed we are advertising widely because we *really* want to hear from users like you!

Regarding renaming the package, while the new name is not a huge issue (we’d probably go with skimage1 or skimage2, in that case; BeautifulSoup has been importing from bs4 for years!), in our earlier discussions we felt that this risks fragmenting the community for a much longer period: people would never know to install scikit-image1 instead of scikit-image.

*If* you’re suggesting changing the import but not the package name, well, that’s definitely an option, but one that I think can be equivalently achieved with `skimage.v0` together with a change of ~all the top level imports. ie *no* scikit-image 0.19 code would ever work silently in 1.0. That might be achievable by keeping the skimage 0.x test suite around and marking it as xfail. =) Or we just go with skimage.v1 and warn that all old skimage code should move to skimage.v0.

An issue with moving the top level import but not the package name is that if the current import never changes and never stops working, then users will simply stay on 0.19 indefinitely and expect it to be supported indefinitely, which is the same as just making a new library. In other words, it removes *all* pressure to upgrade to the new API. This sounds great on the one hand but also like a recipe for an endlessly fragmented community on the other. And anyway, it can be achieved on the user side by pinning the scikit-image dependency to <=0.19.*

Anyway, thank you for taking part in the discussion! We are definitely considering the top-level-import name change option seriously.

At any rate, as mentioned in this thread and in the SKIP, the current deprecation policy in scikit-image means that you should never use scikit-image (or NumPy or SciPy) without an upper version pin, such as <0.21. If you do that, you’ll be golden no matter what happens. =) See this issue for more discussion:




On 20 Jul 2021, at 12:36 pm, Matt Newville <newville@cars.uchicago.edu> wrote:

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.


> 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
Member address: matt.newville@gmail.com

--Matt Newville <newville at cars.uchicago.edu> 630-327-7411
scikit-image mailing list -- scikit-image@python.org
To unsubscribe send an email to scikit-image-leave@python.org
Member address: jni@fastmail.com