diff --git a/docs/upgrading.rst b/docs/upgrading.rst new file mode 100644 --- /dev/null +++ b/docs/upgrading.rst @@ -0,0 +1,69 @@ +.. Copyright (C) 2017 Branko Majic + + This file is part of Django Conntrackt documentation. + + This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 + Unported License. To view a copy of this license, visit + http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative + Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA. + + +Upgrading +========= + +This section covers the necessary upgrade steps between different +versions. + +In general, it is always useful to go thorugh the release notes to +ensure there no surprises are encountered during the upgrade. + +Upgrading from one **patch version** to another (e.g. ``0.3.0`` to +``0.3.1``) should be safe, and should not require any additional steps +beyond installing new package version. Patch versions include only bug +and security-related fixes. + +Upgrading from one **minor version** to another (e.g. ``0.2.0`` to +``0.3.0`` might require some small maintenance tasks, such as running +migrations, or refreshing the static files. In general no breaking +changes should be introduced, and downtime should be minimal. + +Upgrading from one **major version** to another (e.g. ``0.3.1`` to +``1.0.0``) is likely to require a number of changes, and you should +make sure to review both the release notes, and any other documented +instructions outlined below. + +Major version upgrades should be performed only for supported upgrade +paths. This usually means bringing your current installation to the +latest minor release version before jumping to the next major +release. Should you need to jump multiple versions, do it one step at +a time, following along with any necessary changes. Currently +supported upgrade paths are: + +- From version ``0.3.x`` to version ``1.0.x``. + + +Upgrading from ``0.3.x`` to ``1.0.x`` +------------------------------------- + +Version ``1.0.x`` brings in a lot of changes related to dependency +upgrades. This is a big step in terms of Django versions (from Django +1.5.x to Django 1.11.x), with application functionality itself left +untouched. + +In particular, since support for Django 1.5.x has been dropped, you +will need to upgrade your project to Django 1.11.x. Depending on your +project customisations, it may be easier to start a new project and +move over any relevant configuration to it. + +For *Django Conntrackt* itself, at least the following changes must be +made: + +- Removing ``south`` from list of installed applications in project + settings. *Django Conntrackt* now utilises the native migrations. +- Run database migrations with:: + + python manage.py migrate + +- Ensure static data served by external server are up-to-date with:: + + python manage.py collectstatic