# HG changeset patch # User Branko Majic # Date 2017-12-22 12:39:52 # Node ID d7c64b3800af71281fbcd231e4b030595e6f83f8 # Parent fed3c9eee488bf3006af2fd0eb6cc1116a8d855c CONNT-25: Updated documentation: - Marked Django 1.11.x as the only supported Django version. - Updated some copyright notices. - Updated installation and quick-start instructions for use with new version of Django. - Removed unneeded warning about pip version. - Updated instructions to emphasize that 'crispy_forms' must be included in list of installed applications. - Added dedicated section for upgrade instructions. Covered some general principles and upgrade from 0.3.x to 1.0.x. - Updated release notes. - Added information about Graphviz being the external dependency. diff --git a/README.rst b/README.rst --- a/README.rst +++ b/README.rst @@ -28,7 +28,12 @@ At time of this writing, Django Conntrac following Django and Python versions: - *Python 2.7.x* -- *Django 1.5.x* +- *Django 1.11.x* + +In addition, *Django Conntrackt* uses the following external +dependencies: + +- `Graphviz `_ Why was this application created? diff --git a/docs/index.rst b/docs/index.rst --- a/docs/index.rst +++ b/docs/index.rst @@ -1,4 +1,4 @@ -.. Copyright (C) 2013 Branko Majic +.. Copyright (C) 2013-2017 Branko Majic This file is part of Django Conntrackt documentation. @@ -68,6 +68,7 @@ Contents about installation quickstart + upgrading usage development releaseprocedures diff --git a/docs/installation.rst b/docs/installation.rst --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,4 +1,4 @@ -.. Copyright (C) 2013 Branko Majic +.. Copyright (C) 2013-2017 Branko Majic This file is part of Django Conntrackt documentation. @@ -11,7 +11,13 @@ Installation ============ -Django Conntrackt can be installed through one of the following methods: +*Django Conntrackt* has the following prerequisites that need to be +satisfied on the operating system level: + +- `Graphviz `_, used for generating the + diagrams. + +*Django Conntrackt* can be installed through one of the following methods: * Using *pip*, which is the recommended way for production websites. @@ -30,16 +36,6 @@ Mercurial repository, use the following pip install -e hg+http://code.majic.rs/conntrackt#egg=conntrackt -.. warning:: - - You will need to update the ``pip`` installation in your virtual environment if you get the following error while running the above command:: - - AttributeError: 'NoneType' object has no attribute 'skip_requirements_regex' - - You can update ``pip`` to latest version with:: - - pip install -U pip - After this you should proceed to :ref:`configure your Django installation `. @@ -51,8 +47,9 @@ Configuring your Django installation Once the Django Conntrackt has been installed, you need to perform the following steps in order to make it available inside of your Django project: -#. Edit your project's settings configuration file (``settings.py``), and update - the ``INSTALLED_APPS`` to include applications ``south``, ``braces`` and ``conntrackt``. +#. Edit your project's settings configuration file (``settings.py``), + and update the ``INSTALLED_APPS`` to include applications + ``braces``, ``crispy_forms``, and ``conntrackt``. #. Edit your project's URL configuration file (``urls.py``), and add the following line to the ``urlpatterns`` setting:: @@ -61,10 +58,11 @@ steps in order to make it available insi #. Create the necessary tables used for Django Conntrackt by running:: - ./manage.py syncdb + ./manage.py migrate After this the Django Conntrackt application will be available under the ``/conntrackt/`` path (relative to your Django project's base URL). -If you have enabled ``django.contrib.admin``, you should be able to add new -Conntrackt data through the admin interface. +If you have enabled ``django.contrib.admin``, you should be able to +add new Conntrackt data through admin interface as well - in addition +to native data entry provided by application. diff --git a/docs/quickstart.rst b/docs/quickstart.rst --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -1,4 +1,4 @@ -.. Copyright (C) 2013 Branko Majic +.. Copyright (C) 2013-2017 Branko Majic This file is part of Django Conntrackt documentation. @@ -33,16 +33,6 @@ Install Django Conntrackt with its requi workon conntrackt pip install django-conntrackt -.. warning:: - - You will need to update the ``pip`` installation in your virtual environment if you get the following error while running the above command:: - - AttributeError: 'NoneType' object has no attribute 'skip_requirements_regex' - - You can update ``pip`` to latest version with:: - - pip install -U pip - Start a new Django Conntrackt project:: django-admin.py startproject conntrackt_test @@ -50,30 +40,16 @@ Start a new Django Conntrackt project:: Edit configuration file ``conntrackt_test/conntrackt_test/settings.py`` to set-up some basic settings: -#. Under ``DATABASES`` set parameter ``ENGINE`` to ``'django.db.backends.sqlite3'``. -#. Under ``DATABASES`` set parameter ``NAME`` to ``'conntrackt_test.sqlite'``. -#. Under ``INSTALLED_APPS`` uncomment the line ``'django.contrib.admin'``. #. Under ``INSTALLED_APPS`` append lines:: - 'south', + 'crispy_forms', 'braces', 'conntrackt', -#. Append the following lines to the end of the file:: - - from django.conf.global_settings import TEMPLATE_CONTEXT_PROCESSORS - TEMPLATE_CONTEXT_PROCESSORS += ( - "django.core.context_processors.request", - ) - - Edit the URL configuration file ``conntrackt_test/conntrackt_test/urls/.py`` to set-up the URLs for the admin website and Conntrackt itself: #. At the top of the file, add line ``from django.http import HttpResponseRedirect``. -#. Uncomment line ``from django.contrib import admin``. -#. Uncomment line ``admin.autodiscover()``. -#. Uncomment line ``url(r'^admin/', include(admin.site.urls)),`` #. Under ``urlpatterns`` append lines:: url(r'^$', lambda r : HttpResponseRedirect('conntrackt/')), @@ -82,7 +58,6 @@ set-up the URLs for the admin website an Set-up the database for the project:: cd conntrackt_test/ - python manage.py syncdb python manage.py migrate You will be prompted to provide some additional information: @@ -103,4 +78,3 @@ You can now explore the functionality of If you have any problems getting around and understanding how the applications works, have a look at the :ref:`usage guide `. - diff --git a/docs/releasenotes.rst b/docs/releasenotes.rst --- a/docs/releasenotes.rst +++ b/docs/releasenotes.rst @@ -1,4 +1,4 @@ -.. Copyright (C) 2013 Branko Majic +.. Copyright (C) 2013-2017 Branko Majic This file is part of Django Conntrackt documentation. @@ -17,9 +17,10 @@ dev Breaking changes: -* Django Conntrackt now depends on Django 1.10. In addition to official - Django documentation, there is a dedicated upgrade guide that deals - with the most basic installation. +* Django Conntrackt now depends on Django 1.11. In addition to + official Django documentation for project upgrades, there is a + section describing what needs to be done in order to upgrade the + application itself. [ `CONNT-25 `_ ] New features/improvements: 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