Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

[1.5.x] Fixed #17048 - Added docs for upgrading Django.

Thanks Donald Stufft for the suggestion and
Susan Tan and Brian Fabian Crain for the patch.

Backport of ef8a9bc from master.
  • Loading branch information...
commit 1add64684cef6877bf0faeb4a205be6ae07fc98e 1 parent 3f7ecb5
Tim Graham timgraham authored
1  AUTHORS
View
@@ -141,6 +141,7 @@ answer newbie questions, and generally made Django that much better:
crankycoder@gmail.com
Paul Collier <paul@paul-collier.com>
Robert Coup
+ Brian Fabian Crain <http://www.bfc.do/>
Pete Crosier <pete.crosier@gmail.com>
Matt Croydon <http://www.postneo.com/>
Jure Cuhalev <gandalf@owca.info>
1  docs/howto/index.txt
View
@@ -15,6 +15,7 @@ you quickly accomplish common tasks.
custom-template-tags
custom-file-storage
deployment/index
+ upgrade-version
error-reporting
initial-data
jython
91 docs/howto/upgrade-version.txt
View
@@ -0,0 +1,91 @@
+===================================
+Upgrading Django to a newer version
+===================================
+
+While it can be a complex process at times, upgrading to the latest Django
+version has several benefits:
+
+* New features and improvements are added.
+* Bugs are fixed.
+* Older version of Django will eventually no longer receive security updates.
+ (see :ref:`backwards-compatibility-policy`).
+* Upgrading as each new Django release is available makes future upgrades less
+ painful by keeping your code base up to date.
+
+Here are some things to consider to help make your upgrade process as smooth as
+possible.
+
+Required Reading
+================
+
+If it's your first time doing an upgrade, it is useful to read the :doc:`guide
+on the different release processes </internals/release-process>`.
+
+Afterwards, you should familiarize yourself with the changes that were made in
+the new Django version(s):
+
+* Read the :doc:`release notes </releases/index>` for each 'final' release from
+ the one after your current Django version, up to and including the version to
+ which you plan to upgrade.
+* Look at the :doc:`deprecation timeline</internals/deprecation>` for the
+ relevant versions.
+
+Pay particular attention to backwards incompatible changes to get a clear idea
+of what will be needed for a successful upgrade.
+
+Dependencies
+============
+
+In most cases it will be necessary to upgrade to the latest version of your
+Django-related dependencies as well. If the Django version was recently
+released or if some of your dependencies are not well-maintained, some of your
+dependencies may not yet support the new Django version. In these cases you may
+have to wait until new versions of your dependencies are released.
+
+Installation
+============
+
+Once you're ready, it is time to :doc:`install the new Django version
+</topics/install>`. If you are using virtualenv_ and it is a major upgrade, you
+might want to set up a new environment will all the dependencies first.
+
+Exactly which steps you will need to take depends on your installation process.
+The most convenient way is to use pip_:
+
+.. code-block:: bash
+
+ pip install Django
+
+pip_ also automatically uninstalls the previous version of Django.
+
+If you use some other installation process, you might have to manually
+:ref:`uninstall the old Django version <removing-old-versions-of-django>` and
+should look at the complete installation instructions.
+
+.. _pip: http://www.pip-installer.org/
+.. _virtualenv: http://www.virtualenv.org/
+
+Testing
+=======
+
+When the new environment is set up, :doc:`run the full test suite
+</topics/testing/overview>` for your application. In Python 2.7+, deprecation
+warnings are silenced by default. It is useful to turn the warnings on so they
+are shown in the test output (you can also use the flag if you test your app
+manually using ``manage.py runserver``):
+
+.. code-block:: bash
+
+ python -Wall manage.py test
+
+After you have run the tests, fix any failures. While you have the release
+notes fresh in your mind, it may also be a good time to take advantage of new
+features in Django by refactoring your code to eliminate any deprecation
+warnings.
+
+Deployment
+==========
+
+When you are sufficiently confident your app works with the new version of
+Django, you're ready to go ahead and :doc:`deploy </howto/deployment/index>`
+your upgraded Django project.
9 docs/releases/index.txt
View
@@ -6,10 +6,11 @@ Release notes for the official Django releases. Each release note will tell you
what's new in each version, and will also describe any backwards-incompatible
changes made in that version.
-For those upgrading to a new version of Django, 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.
+For those :doc:`upgrading to a new version of Django</howto/upgrade-version>`,
+you will need to check all the backwards-incompatible changes and
+:doc:`deprecated features</internals/deprecation>` for each 'final' release
+from the one after your current Django version, up to and including the new
+version.
Final releases
==============
Please sign in to comment.
Something went wrong with that request. Please try again.