Repository navigation
Conversation
Co-authored-by: Aniket <148300120+Aniketsy@users.noreply.github.com>
Co-authored-by: Aniket <148300120+Aniketsy@users.noreply.github.com>
Co-authored-by: Draga Doncila Pop <17995243+DragaDoncila@users.noreply.github.com>
github-actions
Bot
added
the
documentation
| Deprecating or changing existing API follows the [deprecation | ||
| policy](napari-deprecation-policy). When deprecating a feature, use | ||
| `FutureWarning` instead of `DeprecationWarning`. | ||
| `DeprecationWarning` is | ||
| [silenced by Python's default warning filters](https://docs.python.org/3/library/warnings.html#warning-categories), | ||
| making it invisible to library users. |
There was a problem hiding this comment.
Might be worth mentioninng that for some things we do want to use Deprecation warning, mainly for stuff that is "discouraged" but not planned to be removed yet (e.g: the viewer.scene.camera vs viewer.camera stuff we recently did).
This way, the deprecations will be seen by CI and by static type checkers, but will not spam GUI users.
There was a problem hiding this comment.
I originally had a separate "how to do deprecations" file that I didn't include here -- mostly because I want to clean up napari/src first. So I missed this bit (as you see in the policy its mentioned). I'll make sure I properly mark the to-dos
| This policy is about *notice*. It does not prevent napari from making breaking | ||
| changes — it commits us to telling you about them in advance, on a schedule you | ||
| can plan around. |
There was a problem hiding this comment.
Maybe a mention of how this stems from/relates to EffVer here would be good!
There was a problem hiding this comment.
Do you think I should move the EffVer section up that is two sections down? Or was this a comment from reading through in order.
There was a problem hiding this comment.
I think just a link would be nice :)
| - **Behaviour and default changes.** If the *name* stays but the result changes, | ||
| the same window applies. This matters more than it may appear: napari prioritises | ||
| scientific accuracy, so a changed default can change what a researcher sees in | ||
| their data and therefore is as important, if not more so, than a removed function | ||
| because otherwise the change is silent. |
There was a problem hiding this comment.
How does this look in practice?
Say we change the way colormap maps colors so the colors are slightly different. Do we fire a warnign any time anyones uses a colormap for 2 quarters, and only after that make the change?
This is the kind of problem that EffVer specifically refers to when it says that SemVer doesn't really work, since ANY change is a breaking change, even bug fixes... (as mentioned below, I see now)
There was a problem hiding this comment.
I think this is a great question! There was much support for this idea, in concept, at the core team meeting yesterday. The important thing that we agree is that, especially as a visualization, changes to behavior/defaults is more insidious than deprecations because they can completely change workflow.
Say we change the way
colormapmaps colors so the colors are slightly different. Do we fire a warnign any time anyones uses a colormap for 2 quarters, and only after that make the change?
I thought above this quite a bit, because Python now has PendingDeprecationWarning, I think in pre-1.0 this is just too lofty of a goal. However, I would consider maybe a UserWarning when the thing is changed, and keep it for 2 releases.
However, a simpler solution, for now at least, is to have good tooling and good practiced use of .. versionchanged so that we can autogenerate an API doc that could even be served from the help menu or something, with a homepage tooltip to check it out. Then people could look through added, changed, removed, deprecated listings.
brisvag
added
the
Full docs preview/ready to merge
Co-authored-by: Lundy Bernard <lundybernard@users.noreply.github.com>
for more information, see https://pre-commit.ci
brisvag
removed
the
Full docs preview/ready to merge
|
Given the lack of review from other core team members, I'm going to postpone merging this to the next release. |
References and relevant issues
Description
Time based deprecation policy with a quarterly floor for removal for hard deprecations and a soft deprecation state as well. Formalizes the process to make it easier to search and maintain. This is intended to be a concrete proposal to enable better discussion.
FutureWarningYYYY-QN"DeprecationWarningAlternatives
PendingDeprecationWarningFollow-ups