From 1add64684cef6877bf0faeb4a205be6ae07fc98e Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Wed, 22 May 2013 07:57:36 -0400 Subject: [PATCH] [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 ef8a9bc7fa from master. --- AUTHORS | 1 + docs/howto/index.txt | 1 + docs/howto/upgrade-version.txt | 91 ++++++++++++++++++++++++++++++++++ docs/releases/index.txt | 9 ++-- 4 files changed, 98 insertions(+), 4 deletions(-) create mode 100644 docs/howto/upgrade-version.txt diff --git a/AUTHORS b/AUTHORS index 070ec7003a..357533d7bc 100644 --- a/AUTHORS +++ b/AUTHORS @@ -141,6 +141,7 @@ answer newbie questions, and generally made Django that much better: crankycoder@gmail.com Paul Collier Robert Coup + Brian Fabian Crain Pete Crosier Matt Croydon Jure Cuhalev diff --git a/docs/howto/index.txt b/docs/howto/index.txt index 9d5b067a82..fe25c11756 100644 --- a/docs/howto/index.txt +++ b/docs/howto/index.txt @@ -15,6 +15,7 @@ you quickly accomplish common tasks. custom-template-tags custom-file-storage deployment/index + upgrade-version error-reporting initial-data jython diff --git a/docs/howto/upgrade-version.txt b/docs/howto/upgrade-version.txt new file mode 100644 index 0000000000..d07f9ad07d --- /dev/null +++ b/docs/howto/upgrade-version.txt @@ -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 `. + +Afterwards, you should familiarize yourself with the changes that were made in +the new Django version(s): + +* Read the :doc:`release notes ` 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` 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 +`. 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 ` 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 +` 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 ` +your upgraded Django project. diff --git a/docs/releases/index.txt b/docs/releases/index.txt index 55cb6fdb10..4d10b4ea42 100644 --- a/docs/releases/index.txt +++ b/docs/releases/index.txt @@ -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`, +you will need to check all the backwards-incompatible changes and +:doc:`deprecated features` for each 'final' release +from the one after your current Django version, up to and including the new +version. Final releases ==============