Code

Opened 2 years ago

Closed 22 months ago

Last modified 22 months ago

#18725 closed Cleanup/optimization (worksforme)

Django tutorial should give stronger warning about uninstalling

Reported by: anonymous Owned by: nobody
Component: Documentation Version: 1.4
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: yes
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

Installation of new version of Django while old version is not deleted causes various problems and this is not described in documentation. You should mention this in the very beginning of the tutorial for beginners or make the installation without such problems.

Attachments (0)

Change History (9)

comment:1 Changed 2 years ago by aaugustin

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Resolution set to worksforme
  • Status changed from new to closed

This is documented here and there.

comment:2 Changed 2 years ago by anonymous

But in tutorial https://docs.djangoproject.com/en/dev/intro/tutorial01/
is only this text: "See How to install Django for advice on how to remove older versions of Django and install a newer one.". What if people want to skip installation guide as obvious? Very many do so, as can be seen from problems on django-related forums. And after several hours of frustration each solves problem themselves: "Oh, i forgot to delete old version". Something wrong here, and the problem is in the docs.

comment:3 Changed 2 years ago by anonymous

"worksforme". It's laughable :)) . Program should work for your users. Sorry.

comment:4 Changed 2 years ago by russellm

  • Component changed from Uncategorized to Documentation
  • Easy pickings set
  • Needs documentation set
  • Resolution worksforme deleted
  • Status changed from closed to reopened
  • Summary changed from Django incorrectly updates to Django tutorial should give stronger warning about uninstalling
  • Triage Stage changed from Unreviewed to Accepted
  • Type changed from Uncategorized to Cleanup/optimization

Given the importance of uninstalling older versions before installing new ones, it's probably worth beefing up the note in the tutorial about installation so that it's *very* clear that you have to remove older versions, or hilarity will ensue.

comment:5 Changed 2 years ago by aaugustin

We have to chose what we put at the very beginning of the tutorial, and balance the importance of the different pieces of information. In my opinion, the priorities are:

  • 1) things absolute beginners need to know
  • 2) common pitfalls

Since our docs no longer recommend python setup.py install, you can only encounter this particular problem if you've installed Django at least once in the past — so you aren't a beginner — and if you haven't followed the installation docs in the first place. (By the way this problem may affect all libraries installed in this way, it isn't specific to Django.)

For these reasons, the existing sentence seems sufficient to me. There are dozens of other pitfalls that you can encounter in the tutorial. This one is already mentioned extremely clearly at the very beginning, giving it a very high relative importance. The tutorial 1 already has more "important notes" than text; we can't turn everything into an important note.

At some point, we can't do much for users who don't read the docs (neither the installation instructions nor the advice to uninstall previous versions) and then proceed to make ironic comments here!

comment:6 Changed 2 years ago by ubernostrum

Russ, I do think this is a case where there are limits to how much we can reasonably do at the start of the tutorial. Especially given that you can only run into this if A) you've installed Django before and B) you ignore the instructions we provide, I'm OK with leaving as-is.

comment:7 Changed 22 months ago by nickmartini

I revisited the documentation in question and I saw that immediately before the mentioned link it reads: "Check also that the version number matches the version of this tutorial. If they don't match, you can refer to the tutorial for your version of Django or update Django to the newest version." In order for someone to run into previous version conflicts, they would have to disregard the documentation in place. Furthermore, users only need to uninstall previous versions if they aren't using pip. I suggest we leave the documentation as-is.

Last edited 22 months ago by nickmartini (previous) (diff)

comment:8 Changed 22 months ago by anonymous

  • Resolution set to worksforme
  • Status changed from reopened to closed

If someone's ignoring the existing warnings about this, they're not going to pay attention to more/strongly-worded warnings either. Closing worksforme since the existing docs already tell you to be careful about this issue.

comment:9 Changed 22 months ago by ubernostrum

Blah. Last comment was me, but I wasn't logged in.

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.