Opened 10 years ago
Closed 10 years ago
#23277 closed Cleanup/optimization (wontfix)
set good url examples in 1.7
Reported by: | Collin Anderson | Owned by: | nobody |
---|---|---|---|
Component: | Core (Management commands) | Version: | 1.7-rc-2 |
Severity: | Normal | Keywords: | |
Cc: | cmawebsite@… | Triage Stage: | Unreviewed |
Has patch: | yes | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | no |
Easy pickings: | no | UI/UX: | no |
Change History (15)
comment:2 by , 10 years ago
Please don't change the output of startproject
this late in the release cycle.
comment:3 by , 10 years ago
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.
comment:4 by , 10 years ago
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 be already be deprecated it he next version.
Though it may be smart to mention it in the release notes.
comment:5 by , 10 years ago
Component: | Documentation → Core (Management commands) |
---|
comment:6 by , 10 years ago
Summary: | Backport patterns() documentation changes to 1.7 → set good url examples in 1.7 |
---|
comment:7 by , 10 years ago
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.
comment:8 by , 10 years ago
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.
comment:9 by , 10 years ago
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.
comment:10 by , 10 years ago
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.
comment:11 by , 10 years ago
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.
comment:12 by , 10 years ago
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.
comment:13 by , 10 years ago
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.
comment:14 by , 10 years ago
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.
comment:15 by , 10 years ago
Resolution: | → wontfix |
---|---|
Status: | new → closed |
Okay, I've lost enthusiasm for this. Many readers use the dev docs anyway.
This also changes the urls.py created by
startproject
. https://github.com/django/django/pull/3051