Draft migration guide for skimage2 by lagru · Pull Request #7785 · scikit-image/scikit-image

lagru · 2025-04-29T19:26:39Z

Description

Adds a document with an outline of the planned migration guide. The idea is to compile something like the NumPy 2 migration guide while we work on this.

My gut feeling is that we should keep this guide similarly focused and concise and link to motivation, etc elsewhere.

Checklist

A descriptive but concise pull request title
Docstrings for all functions
Unit tests
A gallery example in ./doc/examples for new features
Contribution guide is followed

Release note

For maintainers and optionally contributors, please refer to the instructions on how to document this PR for the release notes.

...

Documented in https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#code-fences-using-colons

lagru · 2025-04-29T19:28:44Z

doc/source/user_guide/skimage2_migration.md

+Some of these issues involve changes to behavior that are difficult to address with conventional deprecations.
+Since we don't want to change behavior silently, we will introduce the new namespace which gives users an explicit way to upgrade to new behavior.
+
+You can find a more detailed description of our motivation and discussion leading up to this in {doc}`SKIP 4 <../skips/4-transition-to-v2>`.


I'd like to keep this guide focused and concise and would rather link to motivation, etc elsewhere.
So should we update SKIP 4 or is SKIP 5 in order? 😅 I don't really see a reason not to update SKIP 4 which is still has the status "draft".

Thoughts?

Probably worth doing a SKIP 5, since the idea evolved quite a bit over the different proposals.

So should we publish SKIP 4, endorse it, and draft SKIP 5?

Since it's still a draft, I'd say we are free to update and tweak further. I'd prefer that since having another SKIP deal with this problem might become confusing and would also duplicate a lot.

For now I'd just keep in as a "draft". We are planning to tackle the breaking changes for skimage2 soon in a manner that allows toggling between old and new behavior (discussed a few days ago in a meeting). That way we can still make small changes to SKIP 4 if something comes up.

If we make significant changes we can address those in the "Discussion" or "Alternatives" sections.

Does that sound reasonable?

Yes, let's capture what we are currently doing accurately with as little effort as possible.

stefanv · 2025-04-29T23:10:13Z

doc/source/conf.py

    # Enable fieldlist to allow for Field Lists like in rST (e.g., :orphan:)
    "fieldlist",
+    # Enable fencing directives with `:::`
+    "colon_fence",


We support markdown in our docs! Woah, how did I not know this. 😎

MyST comes with its own syntax quirks but I've started to come around to it. I being a superset of markdown seems like a very strong argument to default to it for new documents. 🤔

doc/source/user_guide/skimage2_migration.md

stefanv · 2025-04-29T23:16:18Z

doc/source/user_guide/skimage2_migration.md

+scikit-image is preparing to release version 2.0 under the new namespace `skimage2`.
+This will affect both its import name and its package name on PyPI and elsewhere.
+Together with skimage2, we will release version 1.0.0 and 1.0.1 with the old API.
+Version 1.0.1 will emit a notification (FutureWarning) on import, telling users to either upgrade to skimage2 or pin to version 1.0.0.


I realize now we can't do this, because then we cannot make patch releases to close bugs. So, we'd need to figure out a different scheme.

Maybe 0.XX.Y is the last version without warnings, and 1.0.0 the one with warnings. Or 1.0.X the last without warnings and 1.1.X the one with warnings.

That is a very good point. Maybe we can hack something together using pre-releases since they get special treatment from pip?

1.0.X the last without warnings and 1.1.X the one with warnings

👍

doc/source/user_guide/skimage2_migration.md

stefanv · 2025-04-29T23:20:25Z

doc/source/user_guide/skimage2_migration.md

+We have already introduced a number of changes and deprecations to our API.
+These will only be completed in during the transition to skimage2 and will continue to work in all versions pre-skimage2.
+However, updating your code to the new API will make it easier to transition to the skimage2 API.


We'll edit this text still; leaving it as a placeholder.

Co-authored-by: Stefan van der Walt <[email protected]>

hmaarrfk · 2025-05-01T12:32:31Z

My 2 cents: (and I know I don't chime in a lot).

scikit-image2 seems like a "huge change" that we haven't been able to execute on.

With AI having already scoured all the resources of the internet, i think it is important to "not break the AI context" in 2025. So at least for something like the next 2-4 years, I don't see it as advantageous to have huge breaking changes in the codebase.

Anything that can't be resolved by "deprecators" can be resolved by creating a new function, with a new name.

We can also insert a "switch" for the "integer -> float rescaling" and start to test our codebase with "both modes" and slowly transition.

For me, something that can be done gradually and slowly, is much easier to execute on and can be done by a distributed team with less coordination.

Keeping continuity for our users is also critical and I think scikit-image2 would just break things in ways that we don't want.

stefanv · 2025-05-01T15:46:56Z

Thanks for your input, @hmaarrfk. This has been discussed many times in great detail, and, together, we came up with a plan that is now being executed on.

We all agree that there are risks, but the greatest risk is not moving, and locking up the scarce developer resources we have. For now, we are just doing the footwork for skimage2, which I don't think is controversial.

Once we make the switch, the skimage 1.0 package will be available for others to use, and anyone who wants to work to maintain it is welcome to do so.

FWIW, personally, I could probably have lived with a bunch of ugly keyword flags for ever. That said, I think it's quite reasonable to give ourselves the freedom to change API decisions made 15 years ago. It's not like we'll do this often (it's too painful).

doc/source/user_guide/skimage2_migration.md

mkcor · 2025-05-10T08:58:39Z

doc/source/user_guide/skimage2_migration.md

+scikit-image is preparing to release version 2.0 under the new namespace `skimage2`.
+This will affect both its import name and its package name on PyPI and elsewhere.
+Together with skimage2, we will release version 1.0.0 and 1.0.1 with the old API.
+Version 1.0.1 will emit a notification (FutureWarning) on import, telling users to either upgrade to skimage2 or pin to version 1.0.0.


1.0.X the last without warnings and 1.1.X the one with warnings

👍

doc/source/user_guide/skimage2_migration.md

mkcor · 2025-05-10T09:08:22Z

doc/source/user_guide/skimage2_migration.md

+Some of these issues involve changes to behavior that are difficult to address with conventional deprecations.
+Since we don't want to change behavior silently, we will introduce the new namespace which gives users an explicit way to upgrade to new behavior.
+
+You can find a more detailed description of our motivation and discussion leading up to this in {doc}`SKIP 4 <../skips/4-transition-to-v2>`.


So should we publish SKIP 4, endorse it, and draft SKIP 5?

stefanv · 2025-05-11T01:07:46Z

@mkcor Since this is such an early draft, I'd say go ahead and push any changes you want to see. Thanks for all the suggestions!

stefanv · 2025-05-11T01:08:53Z

Wrt the SKIP, I suppose we make active the version that we're following and reject the others (that sounds harsh, but I think that's the status when you don't implement a PEP / SKIP).

mkcor · 2025-05-12T20:05:08Z

Wrt the SKIP, I suppose we make active the version that we're following and reject the others (that sounds harsh, but I think that's the status when you don't implement a PEP / SKIP).

Right, now I remember that's what we did with SKIP 3! Ok, I'll get the ball rolling then...

doc/source/user_guide/skimage2_migration.md

mkcor · 2025-05-12T21:21:49Z

Ok, I'll get the ball rolling then...

I was about to submit a PR to reject SKIP 4 and a draft PR to create SKIP 5 but, re-reading https://scikit-image.org/docs/dev/skips/4-transition-to-v2.html#implementation, I realize that (except for "scikit-image 0.19" which should be the last "scikit-image 0.x" and, perhaps, "we will publish a user guide" which should be "we will publish a migration guide") all bullet points correspond to my current understanding (as in 89f604d).

I know that, meanwhile, we've had this discussion but, personally, my understanding had (unconsciously?) fallen back to the gist of SKIP 4! If I understand correctly, a draft SKIP is not editable (right?); otherwise I would suggest very minor edits. Anyway, I'd be fine endorsing SKIP 4 as is.

stefanv · 2025-06-11T16:33:47Z

For me, something that can be done gradually and slowly, is much easier to execute on and can be done by a distributed team with less coordination.

Keeping continuity for our users is also critical and I think scikit-image2 would just break things in ways that we don't want.

Hi @hmaarrfk, I've been wanting to get back to this issue to let you know that, during the weekly community meetings, this topic keeps coming up, and that we are aware of the sensitive trade-off being made here. What we've settled on, for now, is to make as many of the changes as we can, even using ugly flags, and to defer the decision on exactly when / whether to "flip the switch" to a further date. This should allow for some breathing room, while not blocking any of the 2.0-related work.

We are planning to update SKIP-4 accordingly.

stefanv

This is a work-in-progress document; merging so we have something to modify in PRs.

* origin/main: Deprecate estimate method in favor of class constructor (scikit-image#7771) Temporary fix for Visual Studio & Clang incompatibility in Windows image (scikit-image#7835) Address deprecations in Pillow 11.3 (scikit-image#7828) Remove unused & obsolete `legacy_datasets`, `legacy_registry` vars (scikit-image#7677) Draft migration guide for skimage2 (scikit-image#7785) Do not report failure in wheels sub-recipe (scikit-image#7806) Use consistent wording in property description. (scikit-image#7804) Add intensity_median to regionprops (scikit-image#7745) CI: Update pypa/gh-action-pypi-publish to v1.12.4 for attestations on PyPI (scikit-image#7793) Document output dtype for transform.resize. (scikit-image#7792) Use `cibuildwheel` to build WASM/Pyodide wheels for `scikit-image`, push nightlies to Anaconda.org (scikit-image#7440) DOC: Include missing gain parameter in adjust_gamma equation (scikit-image#7763) Temporarily pin to `pyodide-build==0.30.0`, and ensure that the correct xbuildenvs are used (scikit-image#7788) Deprecate old names & attributes in RegionProperties (scikit-image#7778) Pin JasonEtco/create-an-issue action to SHA for v2.9.2 (scikit-image#7787) Make doctest-plus work with spin (scikit-image#7786) Report failures on main via issue (scikit-image#7752) Use `workers` instead of alternate parameter names (scikit-image#7302) Fix f-string in otsu plot (scikit-image#7780) Further document use of regionprops function and fix terms. (scikit-image#7518)

* origin/main: (31 commits) Update import convention in certain gallery examples (scikit-image#7764) Refactor fundamental matrix scaling (scikit-image#7767) Add unit test for cval unequal to zero Forward in _generic_edge_filter Remove superfluous mask argument from _generic_edge_filter Only report failure on main branch once Deprecate estimate method in favor of class constructor (scikit-image#7771) Temporary fix for Visual Studio & Clang incompatibility in Windows image (scikit-image#7835) Address deprecations in Pillow 11.3 (scikit-image#7828) Remove unused & obsolete `legacy_datasets`, `legacy_registry` vars (scikit-image#7677) Draft migration guide for skimage2 (scikit-image#7785) Do not report failure in wheels sub-recipe (scikit-image#7806) Use consistent wording in property description. (scikit-image#7804) Add intensity_median to regionprops (scikit-image#7745) CI: Update pypa/gh-action-pypi-publish to v1.12.4 for attestations on PyPI (scikit-image#7793) Document output dtype for transform.resize. (scikit-image#7792) Use `cibuildwheel` to build WASM/Pyodide wheels for `scikit-image`, push nightlies to Anaconda.org (scikit-image#7440) DOC: Include missing gain parameter in adjust_gamma equation (scikit-image#7763) Temporarily pin to `pyodide-build==0.30.0`, and ensure that the correct xbuildenvs are used (scikit-image#7788) Deprecate old names & attributes in RegionProperties (scikit-image#7778) ...

lagru added 2 commits April 29, 2025 21:21

Enable admonitions in Markdown parsed with MyST

4272664

Documented in https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#code-fences-using-colons

Draft skimage2 migration guide

78927d0

lagru added 📄 type: Documentation Updates, fixes and additions to documentation 🥾 Path to skimage2 A step towards the new "API 2.0" labels Apr 29, 2025

lagru requested review from mkcor and stefanv April 29, 2025 19:26

lagru commented Apr 29, 2025

View reviewed changes

stefanv reviewed Apr 29, 2025

View reviewed changes

Add tweaks from review

aba8c2b

Co-authored-by: Stefan van der Walt <[email protected]>

mkcor reviewed May 10, 2025

View reviewed changes

mkcor reviewed May 12, 2025

View reviewed changes

doc/source/user_guide/skimage2_migration.md Outdated Show resolved Hide resolved

Apply suggestions from code review

89f604d

Merge branch 'main' into migration-guide-skimage2

8ab9109

stefanv approved these changes Jun 11, 2025

View reviewed changes

stefanv merged commit c4b6822 into scikit-image:main Jun 11, 2025
21 of 23 checks passed

stefanv added this to the 0.26 milestone Jun 11, 2025

lagru deleted the migration-guide-skimage2 branch June 11, 2025 16:37

Uh oh!

Conversation

lagru commented Apr 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Release note

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lagru May 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hmaarrfk commented May 1, 2025

Uh oh!

stefanv commented May 1, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stefanv commented May 11, 2025

Uh oh!

stefanv commented May 11, 2025

Uh oh!

mkcor commented May 12, 2025

Uh oh!

Uh oh!

mkcor commented May 12, 2025

Uh oh!

stefanv commented Jun 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stefanv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lagru commented Apr 29, 2025 •

edited

Loading

lagru May 15, 2025 •

edited

Loading

stefanv commented Jun 11, 2025 •

edited

Loading