{ "__type": "IngestedDoc", "__tag": 4010, "_content": {}, "_ordered_sections": [], "item_file": null, "item_line": null, "item_type": null, "aliases": [], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "see_also": [], "signature": null, "references": null, "qa": "skips:4-transition-to-v2", "arbitrary": [ { "__type": "Section", "__tag": 4015, "children": [ { "__type": "FieldList", "__tag": 4035, "children": [ { "__type": "FieldListItem", "__tag": 4036, "name": [ { "__type": "Text", "__tag": 4046, "value": "Author" } ], "body": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Juan Nunez-Iglesias " } ] } ] }, { "__type": "FieldListItem", "__tag": 4036, "name": [ { "__type": "Text", "__tag": 4046, "value": "Author" } ], "body": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Lars Grüter" } ] } ] }, { "__type": "FieldListItem", "__tag": 4036, "name": [ { "__type": "Text", "__tag": 4046, "value": "Author" } ], "body": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Stéfan van der Walt" } ] } ] }, { "__type": "FieldListItem", "__tag": 4036, "name": [ { "__type": "Text", "__tag": 4046, "value": "Author" } ], "body": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Matthew Brett" } ] } ] }, { "__type": "FieldListItem", "__tag": 4036, "name": [ { "__type": "Text", "__tag": 4046, "value": "Author" } ], "body": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Marianne Corvellec" } ] } ] }, { "__type": "FieldListItem", "__tag": 4036, "name": [ { "__type": "Text", "__tag": 4046, "value": "Status" } ], "body": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Draft" } ] } ] }, { "__type": "FieldListItem", "__tag": 4036, "name": [ { "__type": "Text", "__tag": 4046, "value": "Type" } ], "body": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Standards Track" } ] } ] }, { "__type": "FieldListItem", "__tag": 4036, "name": [ { "__type": "Text", "__tag": 4046, "value": "Created" } ], "body": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "2025-08-16" } ] } ] }, { "__type": "FieldListItem", "__tag": 4036, "name": [ { "__type": "Text", "__tag": 4046, "value": "Resolved" } ], "body": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "" } ] } ] }, { "__type": "FieldListItem", "__tag": 4036, "name": [ { "__type": "Text", "__tag": 4046, "value": "Resolution" } ], "body": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "" } ] } ] }, { "__type": "FieldListItem", "__tag": 4036, "name": [ { "__type": "Text", "__tag": 4046, "value": "Versioneffective" } ], "body": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "None" } ] } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "SKIP 4 — Transitioning to scikit-image 2.0" } ], "level": 0, "target": "skip_4_transition_v2" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "scikit-image is working towards a 2.0 release. This " }, { "__type": "CrossRef", "__tag": 4002, "value": "is an opportunity", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "skips:3-transition-to-v1" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " to clean up the API, and make long-outstanding backward incompatible changes. Some of these changes involve changing return values without changing function signatures, which cannot be done without adding an otherwise useless keyword argument (such as " }, { "__type": "InlineCode", "__tag": 4051, "value": "new_return_style=True" }, { "__type": "Text", "__tag": 4046, "value": ") whose default value would need to change over several releases. That procedure would still result in backward incompatible changes, but made over a longer time period." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Despite being in beta and in a 0.x series of releases, scikit-image is used extremely broadly, and any backwards incompatible changes are likely to be disruptive. Given the rejection of " }, { "__type": "CrossRef", "__tag": 4002, "value": "SKIP-3", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "skips:3-transition-to-v1" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": ", this document proposes an alternative pathway towards cleaning and modernizing our API. The new pathway involves the following steps:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Introduce a new namespace " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": " that will be included in the package alongside the existing " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": " namespace during a transition period." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The new API will be implemented in " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": " and will initially be marked as unstable and experimental. The old API in " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": " will continue working." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When the new API in " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": " is complete, the old namespace " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": " will be successively deprecated and eventually removed." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See the " }, { "__type": "CrossRef", "__tag": 4002, "value": "skip4_implementation", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "skips:4-transition-to-v2" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " section for a more detailed description of the changes and steps involved." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Abstract" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Admonition", "__tag": 4056, "kind": "note", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "note This is largely duplicated from :ref:`SKIP-3 `." } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "scikit-image has grown organically over the past 12+ years, with functionality being added by a broad community of contributors from different backgrounds. This has resulted in various parts of the API being inconsistent: for example, " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage.transform.warp" }, { "__type": "Text", "__tag": 4046, "value": " inverts the order of coordinates, so that a translation of (45, 32) actually moves the values in a NumPy array by 32 along the 0th axis, and 45 along the 1st, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "but only in 2D" } ] }, { "__type": "Text", "__tag": 4046, "value": ". In 3D, a translation of (45, 32, 77) moves the values in each axis by the number in the corresponding position." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Additionally, as our user base has grown, it has become apparent that certain early API choices turned out to be more confusing than helpful. For example, scikit-image will automatically convert images to various data types, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "rescaling them in the process" } ] }, { "__type": "Text", "__tag": 4046, "value": ". A uint8 image in the range [0, 255] will automatically be converted to a float64 image in [0, 1]. This might initially seem reasonable, but, for consistency, uint16 images in [0, 65535] are rescaled to [0, 1] floats, and uint16 images with 12-bit range in [0, 4095], which are common in microscopy, are rescaled to [0, 0.0625]. These silent conversions have resulted in much user confusion." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Changing this convention would require adding a " }, { "__type": "InlineCode", "__tag": 4051, "value": "preserve_range=" }, { "__type": "Text", "__tag": 4046, "value": " keyword argument to almost " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "all" } ] }, { "__type": "Text", "__tag": 4046, "value": " scikit-image functions, whose default value would change from False to True over 4 versions. Eventually, the change would be backwards-incompatible, no matter how gentle we made the deprecation curve." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Other major functions, such as " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage.measure.regionprops" }, { "__type": "Text", "__tag": 4046, "value": ", could use an API tweak, for example by returning a dictionary mapping labels to properties, rather than a list." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Given the accumulation of potential API changes that have turned out to be too burdensome and noisy to fix with a standard deprecation cycle, principally because they involve changing function outputs for the same inputs, it makes sense to make all those changes in a transition to version 2.0." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Although semantic versioning " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "6" }, { "__type": "Text", "__tag": 4046, "value": " technically allows API changes with major version bumps, we must acknowledge that (1) an enormous number of projects depend on scikit-image and would thus be affected by backwards incompatible changes, and (2) it is not yet common practice in the scientific Python community to put upper version bounds on dependencies, so it is very unlikely that anyone used " }, { "__type": "InlineCode", "__tag": 4051, "value": "scikit-image<1.*" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "scikit-image<2.*" }, { "__type": "Text", "__tag": 4046, "value": " in their dependency list. This implies that releasing a version 2.0 of scikit-image with breaking API changes would disrupt a large number of users. Additionally, such wide-sweeping changes would invalidate a large number of StackOverflow and other user guides. Finally, releasing a new version with a large number of changes prevents users from gradually migrating to the new API: an old code base must be migrated wholesale because it is impossible to depend on both versions of the API. This would represent an enormous barrier of entry for many users." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Given the above, this SKIP proposes that we release a new package where we can apply everything we have learned from over a decade of development, without disrupting our existing user base." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Motivation and Scope" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "It is beyond the scope of this document to list all of the proposed API changes for skimage2, many of which have yet to be decided upon. Indeed, the scope and ambition of the 2.0 transition could grow if this SKIP is accepted. This SKIP instead proposes a mechanism for managing the transition without breaking users' code. A meta-issue tracking the proposed changes can be found on GitHub, scikit-image/scikit-image#5439 " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "7" }, { "__type": "Text", "__tag": 4046, "value": ". Some examples are briefly included below for illustrative purposes:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Stop rescaling input arrays when the dtype must be coerced to float." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Stop swapping coordinate axis order in different contexts, such as drawing or warping." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Allow automatic return of non-NumPy types, so long as they are coercible to NumPy with " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy.asarray" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Harmonizing similar parameters in different functions to have the same name; for example, we currently have " }, { "__type": "InlineCode", "__tag": 4051, "value": "random_seed" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "random_state" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "seed" }, { "__type": "Text", "__tag": 4046, "value": ", or " }, { "__type": "InlineCode", "__tag": 4051, "value": "sample_seed" }, { "__type": "Text", "__tag": 4046, "value": " in different functions, all to mean the same thing." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Changing " }, { "__type": "InlineCode", "__tag": 4051, "value": "measure.regionprops" }, { "__type": "Text", "__tag": 4046, "value": " to return a dictionary instead of a list." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Combine functions that have the same purpose, such as " }, { "__type": "InlineCode", "__tag": 4051, "value": "watershed" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "slic" }, { "__type": "Text", "__tag": 4046, "value": ", or " }, { "__type": "InlineCode", "__tag": 4051, "value": "felzenschwalb" }, { "__type": "Text", "__tag": 4046, "value": ", into a common namespace. This would make it easier for new users to find out which functions they should try out for a specific task. It would also help the community grow around common APIs, where now scikit-image APIs are essentially unique for each function." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "More examples can be found in " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "\"API changes for skimage2\" on our Wiki" } ], "url": "https://github.com/scikit-image/scikit-image/wiki/API-changes-for-skimage2", "title": "" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To make this transition with a minimum amount of user disruption, this SKIP proposes releasing a new namespace, " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": ", that would provide the new API, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "but only if users explicitly opt in" } ] }, { "__type": "Text", "__tag": 4046, "value": ". Additionally, by releasing a new namespace, users could use " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "both" } ] }, { "__type": "Text", "__tag": 4046, "value": " APIs at the same time, allowing users to migrate their code progressively." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Detailed description" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "pandas" }, { "__type": "Text", "__tag": 4046, "value": " released 1.0.0 in January 2020, including many backwards-incompatible API changes " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "3" }, { "__type": "Text", "__tag": 4046, "value": ". SciPy released version 1.0 in 2017, but, given its stage of maturity and position at the base of the scientific Python ecosystem, opted not to make major breaking changes " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "4" }, { "__type": "Text", "__tag": 4046, "value": ". However, SciPy has adopted a policy of adding upper-bounds on dependencies " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "5" }, { "__type": "Text", "__tag": 4046, "value": ", acknowledging that the ecosystem as a whole makes backwards incompatible changes on a 2 version deprecation cycle." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Several libraries have successfully migrated their user community to a new namespace with a version number on it, such as OpenCV (imported as " }, { "__type": "InlineCode", "__tag": 4051, "value": "cv2" }, { "__type": "Text", "__tag": 4046, "value": ") and BeautifulSoup (imported as " }, { "__type": "InlineCode", "__tag": 4051, "value": "bs4" }, { "__type": "Text", "__tag": 4046, "value": "), Jinja (" }, { "__type": "InlineCode", "__tag": 4051, "value": "jinja2" }, { "__type": "Text", "__tag": 4046, "value": ") and psycopg (currently imported as " }, { "__type": "InlineCode", "__tag": 4051, "value": "psycopg2" }, { "__type": "Text", "__tag": 4046, "value": "). Further afield, R's ggplot is used as " }, { "__type": "InlineCode", "__tag": 4051, "value": "ggplot2" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Related Work" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This section documents concrete implementation details, and will be updated as we progress with the v2 implementation." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Implementation" } ], "level": 1, "target": "skip4_implementation" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Two new namespaces and Python packages, " }, { "__type": "InlineCode", "__tag": 4051, "value": "src/_skimage2" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "src/skimage2" }, { "__type": "Text", "__tag": 4046, "value": ", will be created alongside " }, { "__type": "InlineCode", "__tag": 4051, "value": "src/skimage" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "_skimage2" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "will be the temporary namespace, where we build up the new API." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "is a lightweight wrapper around " }, { "__type": "InlineCode", "__tag": 4051, "value": "_skimage2" }, { "__type": "Text", "__tag": 4046, "value": ". It exposes the API for early testing and warns the user on import that " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": " is still unstable." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "With the new namespaces available, we will start building the new API while preserving the existing " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": " namespace and functionality. This process orients itself around the following principles:" } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "One implementation" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If possible, only one implementation should exist, and one API should be a " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "simple" } ] }, { "__type": "Text", "__tag": 4046, "value": " wrapper around the other." } ] } ] } ] }, { "__type": "Target", "__tag": 4061, "label": "sk2-import-hierarchy" }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Import hierarchy" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": " may only import from " }, { "__type": "InlineCode", "__tag": 4051, "value": "_skimage2" }, { "__type": "Text", "__tag": 4046, "value": ", and " }, { "__type": "InlineCode", "__tag": 4051, "value": "_skimage2" }, { "__type": "Text", "__tag": 4046, "value": " should be self-contained. Exceptions (for example, importing from " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": " in " }, { "__type": "InlineCode", "__tag": 4051, "value": "_skimage2" }, { "__type": "Text", "__tag": 4046, "value": ") are temporary and should be realized using inlined imports. By the end of this phase, implementations in " }, { "__type": "InlineCode", "__tag": 4051, "value": "_skimage2" }, { "__type": "Text", "__tag": 4046, "value": " should no longer rely on code in " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Test coverage of both APIs" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": " test suite should be duplicated for " }, { "__type": "InlineCode", "__tag": 4051, "value": "_skimage2" }, { "__type": "Text", "__tag": 4046, "value": " functions. The tests should be adjusted to verify new behavior. To counteract the slowdown due to test duplication, we will soon select tests using dependency analysis (see " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "#7749" } ], "url": "https://github.com/scikit-image/scikit-image/pull/7749", "title": "" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Minimize API difference" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Minimize the differences between the old and new API to make the eventual transition easier for users. Generally, new changes should be introduced in " }, { "__type": "InlineCode", "__tag": 4051, "value": "_skimage2" }, { "__type": "Text", "__tag": 4046, "value": " only. But we may opt for " }, { "__type": "InlineRole", "__tag": 4003, "value": "conventional deprecations ", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " within " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": ", if strong arguments can be made." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Backwards compatible" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "It should be possible to achieve the old behavior of the " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": " API by some call or set of calls with the " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": " API. There may be some situations where we have to break this general rule, but an argument should be made for the relevant change that breaks this rule. In those cases, we will try to provide helper functions instead." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Migration guide" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "We will record the pathway for migrating from the old to the new API in detail in a migration guide. Each API difference will be documented." } ] } ] } ] }, { "__type": "Target", "__tag": 4061, "label": "sk2-local-warning" }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Local deprecation warnings" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Specific deprecation warnings will be added to the old API. These warnings will be silent (subclass of " }, { "__type": "CrossRef", "__tag": 4002, "value": "PendingDeprecationWarning", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "skips:4-transition-to-v2" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": ") and not be shown to users by default." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For example, " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage.data.binary_blobs" }, { "__type": "Text", "__tag": 4046, "value": " may emit a " }, { "__type": "InlineRole", "__tag": 4003, "value": ".PendingSkimage2Change", "domain": null, "role": "class", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " warning that advises users to use " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2.data.binary_blobs" }, { "__type": "Text", "__tag": 4046, "value": " instead and how to adapt to a new signature." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "During this phase, new (additional) features can still be introduced into the old " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": " namespace, not only in the new one." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "First phase: Building " }, { "__type": "InlineRole", "__tag": 4003, "value": "skimage2", "domain": null, "role": null, "inventory": null } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Once we consider the API in " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": " complete and stable, " }, { "__type": "InlineCode", "__tag": 4051, "value": "src/_skimage2" }, { "__type": "Text", "__tag": 4046, "value": " will be merged into " }, { "__type": "InlineCode", "__tag": 4051, "value": "src/skimage2" }, { "__type": "Text", "__tag": 4046, "value": " and the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "experimental" } ] }, { "__type": "Text", "__tag": 4046, "value": " warning will be removed." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Instead, we will mark the API in " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": " as deprecated with a single top-level warning that is raised on import. This warning will encourage users to transition to " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": ". It should link to the migration guide and should explain how to enable " }, { "__type": "CrossRef", "__tag": 4002, "value": "more specific warnings", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "skips:4-transition-to-v2" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "note", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "note " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "At this stage " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": " should no longer need to import from " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": " to avoid triggering this new warning." } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This state will be published in a full release as " }, { "__type": "InlineCode", "__tag": 4051, "value": "scikit-image==2.0.0" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "From that point onward, importing " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": " is encouraged. Development of new features should only happen in " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": ". Bugs in " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": " may still be addressed and will be included in releases with version >= 2.0.0." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "As for conventional deprecations, we will provide users with a grace period of visible warnings for every change necessary for porting from " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": ". This grace period should be at least 2 releases or 2 years long (whichever is longer) before user's code is broken. After this process is complete, we will remove the " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": " namespace entirely." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Second phase: Transitioning to " }, { "__type": "InlineRole", "__tag": 4003, "value": "skimage2", "domain": null, "role": null, "inventory": null } ], "level": 2, "target": "PendingDeprecationWarning" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "While unclear that we will have time to do so, we would like to explore the viability of building a code translation tool, to help users automate the transition to " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": ". This should alleviate the cost and work involved for switching – especially in cases that can be easily automated." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Still, this tool might not support more ambiguous or complex updates of our API, or all the complex ways in which users might use our library. Supporting these cases might be impossible or might require prohibitive development effort. Therefore, users and downstream libraries must always have other means of completing the transition manually, e.g., with the help of conventional deprecation warnings." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If this tool is successfully implemented, it will be included at the start of the second phase as an " }, { "__type": "CrossRef", "__tag": 4002, "value": "entry point", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "skips:4-transition-to-v2" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " alongside " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Code translation helper" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This proposal breaks backward compatibility in numerous places in the library. However, it does so in a new namespace, so that this proposal does not raise backward compatibility concerns for our users. That said, the authors will attempt to limit the number of backward incompatible changes to those likely to substantially improve the overall user experience. It is anticipated that porting " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": " code to " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": " will be a straightforward process and we will publish a user guide for making the transition by the time of the " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": " release. Users will be notified about these resources - among other things - by a warning in scikit-image 1.1." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Backward compatibility" } ], "level": 1, "target": "entry point" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Rationale for design decisions described in the previous section. See " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "Alternatives" } ] }, { "__type": "Text", "__tag": 4046, "value": " for why certain solutions where rejected." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Rationale" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Having additional namespaces significantly simplifies the gradual porting process during the first implementation phase. The new API v2 can be gradually fleshed out in its own independent namespace and made available for testing to the community." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Separating " }, { "__type": "InlineCode", "__tag": 4051, "value": "_skimage2" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": " simplifies the requirement that users are warned about the experimental status of the API v2. Ported implementations that live in " }, { "__type": "InlineCode", "__tag": 4051, "value": "_skimage2" }, { "__type": "Text", "__tag": 4046, "value": " can be reused by wrappers in " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": " without triggering the import warning in " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An alternative would have been to raise this warning not on import of " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": " but when any of its attributes are used, with a custom " }, { "__type": "InlineCode", "__tag": 4051, "value": "__getattr__" }, { "__type": "Text", "__tag": 4046, "value": ". However, we preferred to trigger this warning as early as possible." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Why so many namespaces?" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "While we are gradually porting implementations and API from " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "InlineCode", "__tag": 4051, "value": "_skimage2" }, { "__type": "Text", "__tag": 4046, "value": ", code in one namespace may require functionality from the other one – and vice versa. This can easily lead to confusing circular import errors. To minimize the likelihood of these errors, we define an explicit " }, { "__type": "CrossRef", "__tag": 4002, "value": "sk2-import-hierarchy", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "skips:4-transition-to-v2" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": ". Since we want " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": " to be independent of " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": " by the end of the first phase, we only allow temporary inlined imports from " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Why restrict imports between namespaces?" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "Alternatives" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This is " }, { "__type": "CrossRef", "__tag": 4002, "value": "SKIP-3", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "skips:3-transition-to-v1" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": ", which was rejected after discussion with the community." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Releasing the new API in the same package using semantic versioning" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This transition could occur gradually over many versions. For example, for functions automatically converting and rescaling float inputs, we could add a " }, { "__type": "InlineCode", "__tag": 4051, "value": "preserve_range" }, { "__type": "Text", "__tag": 4046, "value": " keyword argument that would initially default to False, but the default value of False would be deprecated, with users getting a warning to switch to True. After the switch, we could (optionally) deprecate the argument, arriving, after a further two releases, at the same place: scikit-image no longer rescales data automatically, there are no unnecessary keyword arguments lingering all over the API." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Of course, this kind of operation would have to be done simultaneously over all of the above proposed changes." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Ultimately, the core team felt that this approach generates more work for both the scikit-image developers and the developers of downstream libraries, for dubious benefit: ultimately, later versions of scikit-image will still be incompatible with prior versions, although over a longer time scale." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Continuous deprecation over multiple versions" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Since the import name is changing, it would be possible to also change the package name from " }, { "__type": "InlineCode", "__tag": 4051, "value": "scikit-image" }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": " for example. This was proposed in a previous version of this SKIP. It shares many of the same strengths as the current proposal – chiefly – the new " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": " namespace. This option also requires informing users about the new package. Similarly to the suggestion here, we could raise a warning when the old package is imported. It could advise users to install the new package." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "However, managing and releasing two packages from the same repository is problematic. At the same time, introducing a new repository would eventually leave behind issues and pull requests and would also make it prohibitively difficult to implement one API as a wrapper around the other. Therefore, this SKIP recommends keeping the " }, { "__type": "InlineCode", "__tag": 4051, "value": "scikit-image" }, { "__type": "Text", "__tag": 4046, "value": " package name." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "A new package name" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Another possibility is to reject backwards incompatible API changes outright, except in extreme cases. The core team feels that this is essentially equivalent to pinning the library at 0.19." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Not making the proposed API changes" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The authors acknowledge that the new names should be chosen with care to keep the disruption to scikit-image's user base and community as small as possible. However, to protect users without upper version constraints from accidentally upgrading to the new API, the package name " }, { "__type": "InlineCode", "__tag": 4051, "value": "scikit-image" }, { "__type": "Text", "__tag": 4046, "value": " must be changed. Changing the import name " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": " is similarly advantageous because it allows using both APIs in the same environment." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This document suggests just " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": " as the single new name for scikit-image's API version 2.0, both for the import name and the name on PyPI, conda-forge and elsewhere. The following arguments were given in favor of this:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Only one new name is introduced with the project thereby keeping the number of associated names as low as possible." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "With this change, the import and package name match." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Users might be confused whether they should install " }, { "__type": "InlineCode", "__tag": 4051, "value": "scikit-image2" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "scikit-image-2" }, { "__type": "Text", "__tag": 4046, "value": ". It was felt that " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": " avoids this confusion." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Users who know what " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage" }, { "__type": "Text", "__tag": 4046, "value": " is and see " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": " in an install instruction somewhere, will likely be able to infer that it is a newer version of the package." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "It is unlikely that users will be aware of the new API 2.0 but not of the new package name. A proposed release of scikit-image 1.1 might point users to " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": " during the installation and update process and thereby clearly communicate the successors name." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The following arguments were made against naming the package " }, { "__type": "InlineCode", "__tag": 4051, "value": "skimage2" }, { "__type": "Text", "__tag": 4046, "value": ":" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "According to the \"Principle of least astonishment\", " }, { "__type": "InlineCode", "__tag": 4051, "value": "scikit-image2" }, { "__type": "Text", "__tag": 4046, "value": " might be considered the least surprising evolution of the package name." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "It breaks with the convention that is followed by other scikits including scikit-image. (It was pointed out that this convention has not been true for some time and introducing a version number in the name is a precedent anyway.)" } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The earlier section \"Related Work\" describes how other projects dealt with similar problems." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "\"scikit-image2\" as the new package name" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This SKIP is the result of many evolving discussions among the core team, with fellow projects, and with our user base:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "SKIP-3", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "skips:3-transition-to-v1" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " was an earlier iteration of this SKIP. See the \"Resolution\" section of that document for further background on the motivation for this SKIP." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "A pragmatic pathway towards skimage2" } ], "url": "https://discuss.scientific-python.org/t/a-pragmatic-pathway-towards-skimage2/530", "title": "" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Many discussions happened in " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "issues and pull requests tagged as \"Path to skimage2\"" } ], "url": "https://github.com/scikit-image/scikit-image/pulls?q=label%3A%22%3Ahiking_boot%3A+Path+to+skimage2%22+", "title": "" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "meeting notes from the Sprint in Vienna" } ], "url": "https://github.com/scikit-image/skimage-archive/blob/05e98d46b5d12466dcde84487fb75d710adb08b7/sprints/2025-08_sprint_notes_Vienna.md", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " captures part of the extensive discussion that informed this SKIP." } ] } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Discussion" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Pending." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Resolution" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "All SKIPs should be declared as dedicated to the public domain with the CC0 license " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": ", as in " }, { "__type": "InlineRole", "__tag": 4003, "value": "Copyright", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", below, with attribution encouraged with CC0+BY " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Footnote", "__tag": 4067, "label": "1", "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "CC0 1.0 Universal (CC0 1.0) Public Domain Dedication, https://creativecommons.org/publicdomain/zero/1.0/" } ] } ] }, { "__type": "Footnote", "__tag": 4067, "label": "2", "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "https://dancohen.org/2013/11/26/cc0-by/" } ] } ] }, { "__type": "Footnote", "__tag": 4067, "label": "3", "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "https://pandas.pydata.org/pandas-docs/stable/whatsnew/v1.0.0.html#backwards-incompatible-api-changes" } ] } ] }, { "__type": "Footnote", "__tag": 4067, "label": "4", "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "https://docs.scipy.org/doc/scipy/reference/release.1.0.0.html" } ] } ] }, { "__type": "Footnote", "__tag": 4067, "label": "5", "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "https://github.com/scipy/scipy/pull/12862" } ] } ] }, { "__type": "Footnote", "__tag": 4067, "label": "6", "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "https://semver.org/" } ] } ] }, { "__type": "Footnote", "__tag": 4067, "label": "7", "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "https://github.com/scikit-image/scikit-image/issues/5439" } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "References and Footnotes" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This document is dedicated to the public domain with the Creative Commons CC0 license " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": ". Attribution to this source is encouraged where appropriate, as per CC0+BY " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Copyright" } ], "level": 1, "target": null } ], "local_refs": [] }