Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Fixed #17048 -- Added documentation for upgrading Django version #1173

Closed
wants to merge 4 commits into from

3 participants

crainbf Tim Graham Susan  Tan
This page is out of date. Refresh to see the latest.
1  AUTHORS
@@ -157,6 +157,7 @@ answer newbie questions, and generally made Django that much better:
157 157
     Paul Collins <paul.collins.iii@gmail.com>
158 158
     Robert Coup
159 159
     Deric Crago <deric.crago@gmail.com>
  160
+    Brian Fabian Crain <http://www.bfc.do/>
160 161
     David Cramer <dcramer@gmail.com>
161 162
     Pete Crosier <pete.crosier@gmail.com>
162 163
     Matt Croydon <http://www.postneo.com/>
13  docs/howto/deployment/upgrade.txt
... ...
@@ -0,0 +1,13 @@
  1
+---------------------------------------------------------------
  2
+A Short Checklist for Upgrading Your Django Project
  3
+---------------------------------------------------------------
  4
+
  5
+When upgrading your Django project from an older to a newer version, you might run into some hiccups. Here is a checklist of some issues to keep in mind: 
  6
+
  7
+* First, you will need to :ref:`uninstall the old Django version before installing the new version <removing-old-versions-of-django>`. Then, proceed with installing the new version of Django.
  8
+
  9
+* Depending on which release you're upgrading to, you may or may not have to refactor existing code in your Django project to make it compatible with the newer version. This is a :doc:`guide </internals/release-process>` on the different release processes and the type of releases: major, minor, micro. Read the features of the :doc:`various releases </releases/index>` to understand the changes in the new version you're upgrading to. You will need to check all the backwards-incompatible changes and deprecated features for each ‘final’ release from the one after your current Django version, up to and including the new version. 
  10
+
  11
+* Check if the current tests in your Django project are compatible with the new release. Run full test suites on your upgraded Django project and test as many feaures as you can to see where the newly upgraded version is breaking any existing features. 
  12
+
  13
+* It's a good idea to run your tests with Python warnings enabled using the command ``python -Wall manage.py test``. The ``-Wall`` flag tells Python to display deprecation warnings. Django, like many other Python libraries, uses these warnings to flag when features are going away. It also might flag areas in your code that aren't strictly wrong but could benefit from a better implementation. 
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
82  docs/howto/upgrade-version.txt
... ...
@@ -0,0 +1,82 @@
  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 various advantages:
  7
+
  8
+* New features and improvements become available as Django is developed. 
  9
+* Bugs and other problems are fixed. 
  10
+* Continuous upgrades make future upgrades less painful by keeping your code base
  11
+  up to date. 
  12
+* Upgrading ensures your Django version is still maintained.
  13
+
  14
+The following are some things to consider to make your upgrade process as smooth
  15
+as possible.
  16
+
  17
+Release Notes & Getting Ready
  18
+=================
  19
+
  20
+If it is your first time doing an upgrade, it is useful to read the :doc:`guide on the
  21
+different release processes </internals/release-process>`. 
  22
+
  23
+Afterwards before diving in you should familiarize with the changes that were
  24
+made in the new Django version:
  25
+
  26
+* Read all the :doc:`release notes </releases/index>` since the version your upgrading from.
  27
+* Look at the :doc:`deprecation timeline</internals/deprecation>`.
  28
+
  29
+Pay particular attention to backwards incompatible changes to get a clear idea
  30
+of what will be needed for a successful upgrade. 
  31
+
  32
+Dependencies
  33
+=================
  34
+
  35
+A very important subject are dependencies. In most cases it will be necessary to
  36
+upgrade to the latest version of your dependencies as well. 
  37
+If the Django version just came out or some of your dependencies are not 
  38
+well-maintained, they may not yet support the new Django version.
  39
+
  40
+In these cases you might have to wait until new versions of your dependencies 
  41
+are released that support the Django version you want to upgrade to. 
  42
+
  43
+Installation
  44
+=================
  45
+
  46
+Once you're ready, it is time to :doc:`install the new Django version </topics/install>`.
  47
+If you are using virtualenv_ and it is a major upgrade, you might want to set up
  48
+a new environment will all the dependencies first. 
  49
+
  50
+Which steps you need to take depends on the installation process which you use. 
  51
+The most convenient way is to use pip_: 
  52
+
  53
+.. code-block:: bash
  54
+
  55
+   pip install Django
  56
+
  57
+pip_ also automatically uninstalls the previous version of Django. 
  58
+
  59
+If you install Django manually or use some other installation process, you 
  60
+might have to manually :ref:`uninstall the old Django version<removing-old-versions-of-django>` and should look at the
  61
+complete installation instructions. 
  62
+
  63
+.. _pip: http://www.pip-installer.org/
  64
+.. _virtualenv: http://www.virtualenv.org/
  65
+
  66
+Testing
  67
+=================
  68
+
  69
+When the environment is set up, :doc:`run the full test suite </topics/testing/overview>`. In Python 2.7 all
  70
+deprecation warnings are silenced by default. It is useful to turn the warnings
  71
+on for these tests so they are shown in the development server output:
  72
+
  73
+.. code-block:: bash
  74
+
  75
+    python -Wall manage.py test
  76
+
  77
+After you have run the tests, fix and refactor your code until they all pass.
  78
+
  79
+Deployment
  80
+=================
  81
+
  82
+With all the tests passing, you're ready to go ahead and :doc:`deploy </howto/deployment>` your upgraded Django project. 
Commit_comment_tip

Tip: You can add notes to lines in a file. Hover to the left of a line to make a note

Something went wrong with that request. Please try again.