Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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
Showing
4 changed files
with
98 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
This comment has been minimized.
Sorry, something went wrong. |
||
|
||
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Actually that won't work, you need to use
pip install --upgrade Django
or shortpip install -U Django