Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #17048 - Added docs for upgrading Django.

Thanks Donald Stufft for the suggestion and
Susan Tan and Brian Fabian Crain for the patch.
  • Loading branch information...
commit ef8a9bc7fafc394f2c413a6ad4057d67134d742b 1 parent 8c2c178
Tim Graham authored May 22, 2013
1  AUTHORS
@@ -159,6 +159,7 @@ answer newbie questions, and generally made Django that much better:
159 159
     Paul Collins <paul.collins.iii@gmail.com>
160 160
     Robert Coup
161 161
     Deric Crago <deric.crago@gmail.com>
  162
+    Brian Fabian Crain <http://www.bfc.do/>
162 163
     David Cramer <dcramer@gmail.com>
163 164
     Pete Crosier <pete.crosier@gmail.com>
164 165
     Matt Croydon <http://www.postneo.com/>
1  docs/howto/index.txt
@@ -15,6 +15,7 @@ you quickly accomplish common tasks.
15 15
    custom-template-tags
16 16
    custom-file-storage
17 17
    deployment/index
  18
+   upgrade-version
18 19
    error-reporting
19 20
    initial-data
20 21
    jython
91  docs/howto/upgrade-version.txt
... ...
@@ -0,0 +1,91 @@
  1
+===================================
  2
+Upgrading Django to a newer version
  3
+===================================
  4
+
  5
+While it can be a complex process at times, upgrading to the latest Django
  6
+version has several benefits:
  7
+
  8
+* New features and improvements are added.
  9
+* Bugs are fixed.
  10
+* Older version of Django will eventually no longer receive security updates.
  11
+  (see :ref:`backwards-compatibility-policy`).
  12
+* Upgrading as each new Django release is available makes future upgrades less
  13
+  painful by keeping your code base up to date.
  14
+
  15
+Here are some things to consider to help make your upgrade process as smooth as
  16
+possible.
  17
+
  18
+Required Reading
  19
+================
  20
+
  21
+If it's your first time doing an upgrade, it is useful to read the :doc:`guide
  22
+on the different release processes </internals/release-process>`.
  23
+
  24
+Afterwards, you should familiarize yourself with the changes that were made in
  25
+the new Django version(s):
  26
+
  27
+* Read the :doc:`release notes </releases/index>` for each 'final' release from
  28
+  the one after your current Django version, up to and including the version to
  29
+  which you plan to upgrade.
  30
+* Look at the :doc:`deprecation timeline</internals/deprecation>` for the
  31
+  relevant versions.
  32
+
  33
+Pay particular attention to backwards incompatible changes to get a clear idea
  34
+of what will be needed for a successful upgrade.
  35
+
  36
+Dependencies
  37
+============
  38
+
  39
+In most cases it will be necessary to upgrade to the latest version of your
  40
+Django-related dependencies as well. If the Django version was recently
  41
+released or if some of your dependencies are not well-maintained, some of your
  42
+dependencies may not yet support the new Django version. In these cases you may
  43
+have to wait until new versions of your dependencies are released.
  44
+
  45
+Installation
  46
+============
  47
+
  48
+Once you're ready, it is time to :doc:`install the new Django version
  49
+</topics/install>`. If you are using virtualenv_ and it is a major upgrade, you
  50
+might want to set up a new environment will all the dependencies first.
  51
+
  52
+Exactly which steps you will need to take depends on your installation process.
  53
+The most convenient way is to use pip_:
  54
+
  55
+.. code-block:: bash
  56
+
  57
+   pip install Django
  58
+
  59
+pip_ also automatically uninstalls the previous version of Django.
  60
+
  61
+If you use some other installation process, you might have to manually
  62
+:ref:`uninstall the old Django version <removing-old-versions-of-django>` and
  63
+should look at the complete installation instructions.
  64
+
  65
+.. _pip: http://www.pip-installer.org/
  66
+.. _virtualenv: http://www.virtualenv.org/
  67
+
  68
+Testing
  69
+=======
  70
+
  71
+When the new environment is set up, :doc:`run the full test suite
  72
+</topics/testing/overview>` for your application. In Python 2.7+, deprecation
  73
+warnings are silenced by default. It is useful to turn the warnings on so they
  74
+are shown in the test output (you can also use the flag if you test your app
  75
+manually using ``manage.py runserver``):
  76
+
  77
+.. code-block:: bash
  78
+
  79
+    python -Wall manage.py test
  80
+
  81
+After you have run the tests, fix any failures. While you have the release
  82
+notes fresh in your mind, it may also be a good time to take advantage of new
  83
+features in Django by refactoring your code to eliminate any deprecation
  84
+warnings.
  85
+
  86
+Deployment
  87
+==========
  88
+
  89
+When you are sufficiently confident your app works with the new version of
  90
+Django, you're ready to go ahead and :doc:`deploy </howto/deployment/index>`
  91
+your upgraded Django project.
9  docs/releases/index.txt
@@ -6,10 +6,11 @@ Release notes for the official Django releases. Each release note will tell you
6 6
 what's new in each version, and will also describe any backwards-incompatible
7 7
 changes made in that version.
8 8
 
9  
-For those upgrading to a new version of Django, you will need to check
10  
-all the backwards-incompatible changes and deprecated features for
11  
-each 'final' release from the one after your current Django version,
12  
-up to and including the new version.
  9
+For those :doc:`upgrading to a new version of Django</howto/upgrade-version>`,
  10
+you will need to check all the backwards-incompatible changes and
  11
+:doc:`deprecated features</internals/deprecation>` for each 'final' release
  12
+from the one after your current Django version, up to and including the new
  13
+version.
13 14
 
14 15
 Final releases
15 16
 ==============

0 notes on commit ef8a9bc

Jannis Leidel

Actually that won't work, you need to use pip install --upgrade Django or short pip install -U Django

Please sign in to comment.
Something went wrong with that request. Please try again.