Breaking change for 2.0: app_name no longer in include, but in urls.py

[Christian Kreuzberger]

I believe I found a way to improve the documentation for the upcoming 2.0 release. I found out about this as I had an old 1.8 app that I am trying to get compatible with 1.11 and 2.0.

The "breaking changes" documentation in the 2.0 release notes states that

• The app_name argument to include() is removed.

However, it does not state that you now should (or even have to) specify the app_name attribute in your urls.py.

With Django 1.8 to 1.11 the following did work:

myproject/urls.py:

from django.conf.urls import url, include
from myproject.views import reset_password_request_token, reset_password_confirm

urlpatterns = [
    url(r'^confirm', reset_password_confirm, name="reset-password-confirm"),
    url(r'^', reset_password_request_token, name="reset-password-request"),
]

Somewhere else in the main urls.py:

urlpatterns = [
    url(r'^api/password_reset/', include('myproject.urls', namespace='myproject')),
]

With 2.0 you will get the following error:

 File "~/myproject/venv/lib/python3.5/site-packages/django/urls/conf.py", line 39, in include
    'Specifying a namespace in include() without providing an app_name '
django.core.exceptions.ImproperlyConfigured: Specifying a namespace in include() without providing an app_name is not supported. Set the app_name attribute in the included module, or pass a 2-tuple containing the list of patterns and app_name instead.

The obvious fix is to specify app_name in myproject/urls.py like this:

from django.conf.urls import url, include
from myproject.views import reset_password_request_token, reset_password_confirm

app_name="myproject"

urlpatterns = [
    url(r'^confirm', reset_password_confirm, name="reset-password-confirm"),
    url(r'^', reset_password_request_token, name="reset-password-request"),
]

I believe it might be worth adding this information to the list of breaking changes, stating that you have to specify the app_name attribute in your urls.py now. Might also be worth linking to the documentation for configuring urls.py properly, as app_name has been in there since 1.9:
​https://docs.djangoproject.com/en/2.0/topics/http/urls/#url-namespaces-and-included-urlconfs

[Tim Graham]

The details about that change are in ​in the 1.9 release notes which is linked to from the top of the "Features removed in 2.0" section: "These features have reached the end of their deprecation cycle and are removed in Django 2.0. See Features deprecated in 1.9 and Features deprecated in 1.10 for details, including how to remove usage of these features."

[Christian Kreuzberger]

Thank you for taking the time, and also for linking the 1.9 release notes. I was foolish enough to not look into those in detail, as I just worked my way through the 2.0 release notes (and not the linked sub-pages).

Anyway, I believe that the issue at hand is exactly that. One has to go through the "Features deprecated in 1.9" and "Features deprecated in 1.10" lists every time they come across a problem when upgrading to 2.0. I guess that's the way it always has been with prior releases?

Don't get me wrong, I'm not complaining about the lack of documentation. The Django documentation is one of the best open source project documentations I have seen so far.

What I would like to see for the Release Information is some way to cross-reference the information for deprecated features, like "The app_name argument to include() is removed. - Deprecated in Django 1.9 (Link to Features Deprecated in 1.9)".

[Tim Graham]

The "Features removed" section is there for ease of searching. In older release notes, we didn't even have that section and only linked to the deprecation notes.

I think linking every item in the list would be more work than it's worth (and it's not possible for some items since items in the "Miscellaneous" section don't have their headers), but I pushed a small improvement in 50de55f39984e0b83ba760192b1ecd10e5737c3d.