Commit 1add6468 authored by Tim Graham's avatar Tim Graham
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 ef8a9bc7 from master.
parent 3f7ecb51

AUTHORS

+1 −0
Original line number Diff line number Diff line
@@ -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>

docs/howto/index.txt

+1 −0
Original line number Diff line number Diff line
@@ -15,6 +15,7 @@ you quickly accomplish common tasks. 
   custom-template-tags

   custom-file-storage

   deployment/index

   upgrade-version

   error-reporting

   initial-data

   jython

docs/howto/upgrade-version.txt

0 → 100644
+91 −0
Original line number Diff line number Diff line 
===================================

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.

docs/releases/index.txt

+5 −4
Original line number Diff line number Diff line
@@ -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

==============