Backwards-compatibility import shims

[Marten Kenbeek]

As noted by Collin on deprecating old import paths:

I personally wouldn't mind if we didn't actually deprecate this, and left these shims in a bit longer :). (Makes it just a hair easier for people upgrading.) But that's just me.

There is very little maintenance overhead to keep backwards-compatible import shims longer than the current deprecation cycle.

Any thoughts on this?

[Tim Graham]

To save a link click, the question is about moving django.core.urlresolvers to django.urls and whether or not to start the deprecating of django.core.urlresolvers immediately.

I don't have a strong opinion myself. On one hand, delaying gives projects more time to update, on the other, I suspect many projects will continue using django.core.urlresolvers in new code if there's no indication that it's deprecated.

[Marten Kenbeek]

One solution is to create a RemovedInFutureVersionWarning to allow projects to catch the change when running with -Wall, without committing to a specific release.

[Tim Graham]

Given that alternate, I guess I'm not really enthusiastic about making our deprecation policy more complicated. While urlresolvers is a commonly used module, updating should be a simple find and replace for the imports.

On the other hand, I thought of a slight flaw in our current deprecation scheme. If a third-party library wants to support both 1.8 and 1.11 (next LTS) would have to use a try (new import)/except (old import) pattern to avoid code running on 1.11 from raising deprecation warnings (some pending deprecation in 1.10, deprecated in 1.11, and removed in 2.0). In my mind, part of the purpose of the new policy was to avoid this type of complexity.

For that reason, I think we should reconsider making Django's deprecation warnings loud by default (at least in LTS versions) [1]. Otherwise, users will pester library authors to fix those warnings and we haven't really made things easier.

Instead, the idea would be for library authors to continue using the deprecated APIs while supporting the LTS in which they are deprecated and the previous LTS. When the version of Django following the LTS is released, library authors can then drop support for all Django versions before the LTS, check their package with the LTS using python -Wall and make the deprecation warning fixes, then seamlessly add support for the next version of Django.

Does that make sense?

[1] slightly related: https://code.djangoproject.com/ticket/25999

[Michael Manfre]

On Wed, Dec 30, 2015 at 11:52 AM, Tim Graham <timog...@gmail.com> wrote:

For that reason, I think we should reconsider making Django's deprecation warnings loud by default (at least in LTS versions) [1]. Otherwise, users will pester library authors to fix those warnings and we haven't really made things easier.

Instead, the idea would be for library authors to continue using the deprecated APIs while supporting the LTS in which they are deprecated and the previous LTS. When the version of Django following the LTS is released, library authors can then drop support for all Django versions before the LTS, check their package with the LTS using python -Wall and make the deprecation warning fixes, then seamlessly add support for the next version of Django.

Does that make sense?

This makes sense to me. +1

Regards,

Michael Manfre

--

GPG Fingerprint: 74DE D158 BAD0 EDF8

keybase.io/manfre

[Collin Anderson]

Hi All,

tldr: I think we should keep django.core.urlresolvers forever, or at least much much longer. Moving things to django.core.urls makes sense; removing the one line import shim from django.core.urlresolvers doesn't make sense to me.

General thoughts about compatibility, using this situation an example:

I think that if it's not broken, we should avoid breaking it. :) Some features are buggy or problematic or have bad api design and should be deprecated and removed. This is a simple rename so it only requires one file with one line of code (an import statement) to maintain full backwards compatibility here. Maybe we need also need a little doc stub saying that django.core.urlresolvers was renamed to django.core.urls and the new location is preferred. It seems to me when there's almost zero maintenance burden to not removing something, we shouldn't remove it, especially when it's an established and core api.

We have a stable api promise[1], and we should stick to it. "If, for some reason, an API declared stable must be removed or replaced, it will be declared deprecated but will remain in the API for at least two feature releases". I don't see this as a "must" situation.

There's enough changes to undocumented api's already happening that it would be great if the documented ones didn't change as much.

I hard code most of my urls, so it's only 41 lines of my code across 7 projects of mine that would need to eventually get changed. Sure, it's a simple find and replace, but it's one more thing that almost every django project maintainer will need to eventually do.

Or, maybe I'm the the only one who thinks we deprecate and remove things too often. I feel like I ask for backwards compatibility a lot, even though I haven't been helping out with django as much as I used to.

Again, there's nothing specific about this case, there are plenty of other changes that I wish I noticed and spoke up about earlier: (assignment_tag, patterns(), django.conf.urls.defaults, generic.simple, etc).

And to be clear, some deprecations (like removing allow_tags) are really, really good. :)

Thanks,

Collin

[1] https://docs.djangoproject.com/en/dev/misc/api-stability/