set good url examples in 1.7

[Collin Anderson]

#22218 deprecated patterns in 1.8, though I think it would be good to at least set a good example in the 1.7 documentation. See also #23276

[Collin Anderson]

This also changes the urls.py created by startproject. ​https://github.com/django/django/pull/3051

[Mark Lavin]

Please don't change the output of startproject this late in the release cycle.

[Tim Graham]

Mark, could you elaborate on your concerns as to the negative consequences changing the project template would have? It would be nice to propagate best practices for everyone starting a new project, but you can convince me otherwise.

[Collin Anderson]

I also am personally a little hesitant with removing patterns() from project_template this late in the game, but in theory, it's just for new projects. I'm hoping that the next 9-12 months worth of manage.py startproject will be happy that this change was made, as it will already be deprecated by the next version.

Though it may be smart to mention it in the release notes.

[Mark Lavin]

Some people in the community (including myself) are working on tutorials, books and other resources targeting 1.7 and deserve the stability guaranteed by the release process docs to create those materials. ​https://docs.djangoproject.com/en/1.7/internals/release-process/#phase-three-bugfixes states

After the release candidate, only release blockers and documentation fixes should be backported.

But this exceeds a documentation change.

[Mark Lavin]

For example "Test-Driven Web Development with Python" has sold printed copied stating that the generated urls.py will use patterns Django 1.7 ​http://chimera.labs.oreilly.com/books/1234000000754/ch03.html#_urls_py The online version can be updated but those already printed cannot. Technical authors understand that their books will become out of date very quickly but Harry has worked too hard and his book helps this community too much to deserve this change.

[Tim Graham]

Yes, I am torn between making this change and obsoleting some print books that have sold before Django 1.7 is finalized and the benefit that everyone who starts a project in the next 9-12 months will reap with respect to not having to eventually remove deprecated behavior from their projects. In doubt, I guess we should stick with our official policy and not make the change in the template. Assuming we don't make the change, we could add a step to the tutorial telling users how to remove the deprecated behavior. Of course, I am biased to the path that doesn't lead to this awkward moment in the Django docs.

[Mark Lavin]

Django has a working deprecation timeline. Using patterns with 1.7 will not cause any unexpected behavior or raise any level of deprecation warning. The same is true for 1.6, 1.5, 1.4 and so on. It is completely acceptable usage. Starting with 1.8 patterns will be deprecated and that cruft will be removed in due time. I'm happy to see it go and thankful for your work in helping remove it but there is no need to rush the process here.

The people helped by this change are those who start a project on 1.7, don't read the release notes or deprecation warnings for the next 2-3 years, and are bitten by the removal of patterns when they try to upgrade to 2.0. I personally have very little sympathy for them.

[Carl Meyer]

FWIW, I think mlavin is correct here; we need far better reasons than this to violate the promises made in our release-process docs. Someone who has already published a book about Django 1.7 based on the behavior of a release-candidate is not doing anything wrong; they are simply relying on the commitments we've made. That's why those commitments exist. Advance publishing is good for us and for the community; it means that Django-1.7-targetted resources can be available the moment 1.7 final comes out. It would be bad behavior on our part to violate our documented process and render the book apparently obsolete/wrong in the eyes of its readers.

I don't think there is any need for an added "remove this" step in the tutorial creating an "awkward moment" in the docs. Let the deprecation timeline work normally. patterns is not deprecated yet in Django 1.7, and that's fine.

[Tim Graham]

Okay, how do you guys feel about the rest of the doc changes then? I guess it could be confusing for newbies if they see patterns() in their new project but no where else.

[Carl Meyer]

Yeah, I can see that too. Probably clearest and simplest to just leave 1.7 alone, so that the deprecation, startproject, and all the docs change with the same release. It's a nice idea to give people an extra release "jump" on this particular deprecation timeline, but I don't think it's worth the extra fuss of having to explain to people "well, this is the new preferred way, used throughout the 1.7 docs, but startproject doesn't use it yet until 1.8". This is not a difficult deprecation to adjust to, projects started under 1.7 (and people referring to the 1.7 docs) will be fine, just like all the people with projects started in every earlier version of Django.

If you prefer to go ahead with the docs changes, I don't think the inconsistency would be a huge deal either. But I'd lean towards leaving 1.7 alone.

[Mark Lavin]

I don't have a strong objection to the doc changes. I don't find the inconsistency that hard to grasp and I'm not sure most readers will even notice it. But I'm also not new to Django and I'm aware of the change in 1.8 which is not true for many readers. At the same time, I don't think there is a need to future-proof the 1.7 docs for upcoming changes. Users will have two release cycles to adjust to the change once 1.8 is released. If there is a question I would also error on the side of conservative changes to 1.7.

[Tim Graham]

Okay, I've lost enthusiasm for this. Many readers use the dev docs anyway.