Merge pull request #550 from gwasser/master

Update documentation for explicitly Django 1.11.x

CONTRIBUTING.rst

@@ -13,18 +13,105 @@ https://github.com/django-helpdesk/django-helpdesk
 Licensing
 ---------
 
-All contributions to django-helpdesk must be under the BSD license documented in
+All contributions to django-helpdesk *must* be under the BSD license documented
-the LICENSE file in the top-level directory of this project.
+in the LICENSE file in the top-level directory of this project.
 
 By submitting a contribution to this project (in any way: via e-mail,
-via GitHub forks, attachments, etc), you acknowledge that your contribution is
+via GitHub pull requests, ticket attachments, etc), you acknowledge that your
-open-source and licensed under the BSD license.
+contribution is open-source and licensed under the BSD license.
 
 If you or your organisation does not accept these license terms then we cannot
 accept your contribution. Please reconsider!
 
-Translations
+Ways to Contribute
-------------
+------------------
+
+We're happy to include any type of contribution! This can be:
+* back-end python/django code development
+* front-end web development (HTML/Javascript, especially jQuery)
+* language translations
+* writing improved documentation and demos
+
+More details on each of theses tasks is below.
+
+If you have any questions on contributing, please start a discussion on
+the GitHub issue tracker at
+
+https://github.com/django-helpdesk/django-helpdesk/issues
+
+### Back-end Python/Django
+
+Please fork the project on GitHub, make your changes, and submit a
+pull request back into the appropriate branch of the
+django-helpdesk repository.
+
+In general, we use the following git branching scheme:
+* `master` always refers to development for the next major release
+* major releases are found in their own branches
+** `0.2.x` is the branch for the 0.2 release and any bugfix releases
+** `0.1` is the branch for the legacy code; it is no longer supported
+
+If you are submitting a patch for a 0.2 release, apply your pull request
+to the `0.2.x` branch. If you are helping develop the next release,
+apply your patches to the `master` branch.
+
+Wherever possible please break git commits up into small chunks that are
+specific to a single bit of functionality. For example, a commit should *not*
+contain both new functionality *and* a bugfix; the new function and the bugfix
+should be separate commits wherever possible.
+
+Commit messages should also explain *what*, precisely, has been changed.
+
+All commits should include appropriate new or updated tests; see the Tests
+section below for more details.
+
+If your changes affect the Django models for django-helpdesk, be aware
+that your commits should include database schema python scripts; see the
+Database Schema Changes section below for more details.
+
+#### Tests
+
+Currently, test coverage is very low. We're working on increasing this, and to
+make life easier we are using Travis CI (http://travis-ci.org/) for continuous
+integration. This means that the test suite is run every time a code change is
+made, so we can try and make sure we avoid basic bugs and other regressions.
+
+As a general policy, we will only accept new feature commits if they are
+accompanied by appropriate unit/functional tests (that is, tests for the
+functionality you just added). Bugfixes should also include new unit tests to
+ensure the bug has been fixed.
+
+More significant code refactoring must also include proper integration or
+validation tests, to be committed *BEFORE* the refactoring patches. This is to
+ensure that the refactored code produces the same results as the previous code
+base.
+
+Any further integration or validation tests (tests for the entire
+django-helpdesk application) are not required but greatly appreciated until we
+can improve our overall test coverage.
+
+Please include tests in the ``tests/`` folder when committing code changes.
+
+If you have any questions about creating or maintaining proper tests, please
+start a discussion on the GitHub issue tracker at
+
+https://github.com/django-helpdesk/django-helpdesk/issues
+
+#### Database schema changes
+
+As well as making your normal code changes to ``models.py``, please generate a
+Django migration file and commit it with your code. You will want to use a
+command similar to the following::
+
+    ./manage.py migrate helpdesk --auto [migration_name]
+
+Make sure that ``migration_name`` is a sensible single-string explanation of
+what this migration does, such as *add_priority_options* or *add_basket_table*.
+
+This will add a file to the ``migrations/`` folder, which must be committed to
+git with your other code changes.
+
+### Translations
 
 Although django-helpdesk has originally been written for the English language,
 there are already multiple translations to Spanish, Polish, German and Russian.
@@ -40,69 +127,3 @@ http://www.transifex.net/projects/p/django-helpdesk/resource/core/
 
 Once you have translated content via Transifex, please raise an issue on the
 project Github page to let us know it's ready to import.
-
-Code changes
-------------
-
-Please fork the project on GitHub, make your changes, and log a pull request to
-get the changes pulled back into the
-master branch of the django-helpdesk repository.
-
-Wherever possible please break git commits up into small chunks that are
-specific to a single bit of functionality. For example, a commit should not
-contain both new functionality *and* a bugfix; the new function and the bugfix
-should be separate commits wherever possible.
-
-Commit messages should also explain *what*, precisely, has been changed.
-
-All commits should include appropriate new or updated tests; see the Tests
-section below for more details.
-
-If you have any questions, please start a discussion on the GitHub issue tracker
-at
-
-https://github.com/django-helpdesk/django-helpdesk/issues
-
-Tests
------
-
-Currently, test coverage is very low. We're working on increasing this, and to
-make life easier we are using `Travis CI` (http://travis-ci.org/) for continuous
-integration. This means that the test suite is run every time a code change is
-made, so we can try and make sure we avoid basic bugs and other regressions.
-
-As a general policy, we will only accept new feature commits if they are
-accompanied by appropriate unit/functional tests (that is, tests for the
-functionality you just added). Bugfixes should also include new unit tests to
-ensure the bug has been fixed.
-
-More significant code refactoring must also include proper integration or
-validation tests, to be committed BEFORE the refactoring patches. This is to
-ensure that the refactored code produces the same results as the previous code
-base.
-
-Any further integration or validation tests (tests for the entire
-django-helpdesk application) are not required but greatly appreciated until we
-can improve our overall test coverage.
-
-Please include tests in the ``tests/`` folder when committing code changes.
-
-If you have any questions about creating or maintaining proper tests, please
-start a discussion on the GitHub issue tracker at
-
-https://github.com/django-helpdesk/django-helpdesk/issues
-
-Database schema changes
------------------------
-
-As well as making your normal code changes to ``models.py``, please generate a
-Django migration file and commit it with your code. You will want to use a
-command similar to the following::
-
-    ./manage.py migrate helpdesk --auto [migration_name]
-
-Make sure that ``migration_name`` is a sensible single-string explanation of
-what this migration does, such as *add_priority_options* or *add_basket_table*.
-
-This will add a file to the ``migrations/`` folder, which must be committed to
-git with your other code changes.

README.rst

@@ -36,55 +36,60 @@ Demo Quickstart
 
 django-helpdesk includes a basic demo Django project so that you may easily
 get started with testing or developing django-helpdesk. The demo project
-resides in the demo/ top-level folder.
+resides in the `demo/` top-level folder.
 
 It's likely that you can start up a demo project server by running
-only the command:
+only the command::
 
     sudo make rundemo
 
-then pointing your web browser at localhost:8080.
+then pointing your web browser at `localhost:8080`.
 
-For more information and options, please read the demo/README.rst file.
+For more information and options, please read the `demo/README.rst` file.
 
 **NOTE REGARDING SQLITE AND SEARCHING:**
-The demo project uses sqlite as its database. Sqlite does not allow
+The demo project uses `sqlite` as its database. Sqlite does not allow
 case-insensitive searches and so the search function may not work as
 effectively as it would on other database such as PostgreSQL or MySQL
 that does support case-insensitive searches.
-For more information, see this note in the Django documentation:
+For more information, see [this note in the Django documentation](http://docs.djangoproject.com/en/dev/ref/databases/#sqlite-string-matching).
-http://docs.djangoproject.com/en/dev/ref/databases/#sqlite-string-matching
 
-When you try to do a keyword search using sqlite, a message will be displayed
+When you try to do a keyword search using `sqlite`, a message will be displayed
 to alert you to this shortcoming. There is no way around it, sorry.
 
 Installation
 ------------
 
-django-helpdesk requires either Python 2.7 or 3.4+, as well as Django 1.11+.
+`django-helpdesk` requires:
+* Django 1.11.x *only*
+* either Python 2.7 or 3.4+
 
 **NOTE REGARDING PYTHON VERSION:**
-The recommended combination is Python 3.4+ with Django 1.11+.
+The recommended combination is Python 3.4+ with Django 1.11.
-Support for Python 2 will end in the next versions of both django-helpdesk
+Support for Python 2 will end in the next versions of both `django-helpdesk`
-and Django itself (2.0), so users and developers are encouraged to begin
+and Django itself (Django 2.0), so users and developers are encouraged to begin
-transitioning to Python 3 if have not already.
+transitioning to Python 3 if have not already. New projects should definitely
+use Python 3!
 
-You can quickly install the latest stable version of django-helpdesk app via pip:
+You can quickly install the latest stable version of `django-helpdesk`
+app via `pip`::
 
     pip install django-helpdesk
 
-You may also check out the master branch on GitHub, and install manually:
+You may also check out the `master` branch on GitHub, and install manually::
 
     python setup.py install
 
-Either way, you will need to add django-helpdesk to an existing Django project.
+Either way, you will need to add `django-helpdesk` to an existing
+Django project.
 
-For further installation information see docs/install.html and docs/configuration.html
+For further installation information see `docs/install.html`
+and `docs/configuration.html`
 
 Upgrading from previous versions
 --------------------------------
 
-If you are upgrading from a previous version of django-helpdesk that used
+If you are upgrading from a previous version of `django-helpdesk` that used
 migrations, get an up to date version of the code base (eg by using
 `git pull` or `pip install --upgrade django-helpdesk`) then migrate the database::
 
@@ -95,15 +100,17 @@ Lastly, restart your web server software (eg Apache) or FastCGI instance, to
 ensure the latest changes are in use.
 
 Unfortunately we are unable to assist if you are upgrading from a
-version of django-helpdesk prior to migrations (ie pre-2011).
+version of `django-helpdesk` prior to migrations (ie pre-2011).
 
 You can continue to the 'Initial Configuration' area, if needed.
 
 Contributing
 ------------
 
-We're happy to include any type of contribution! This can be back-end
+We're happy to include any type of contribution! This can be:
-python/django code development, front-end web development
+* back-end python/django code development
-(HTML/Javascript, especially jQuery), or even language translations.
+* front-end web development (HTML/Javascript, especially jQuery)
+* language translations
+* writing improved documentation and demos
 
-For more information on contributing, please see the CONTRIBUTING.rst file.
+For more information on contributing, please see the `CONTRIBUTING.rst` file.

demo/README.rst

@@ -74,8 +74,10 @@ Then navigate to the site in a browser as above.
 *NOTE ON DJANGO VERISON*
 
 The demo project was also created with Django 1.11
-in mind. If you are using a different version of Django,
+in mind. If you are using an older version of Django,
 slight tweaks might be necessary to make the demo work.
+Please remember that we do not currently support any
+version of Django other than 1.11.
 
 *NOTE ON ATTACHMENTS*
 

helpdesk/models.py

@@ -259,6 +259,7 @@ class Queue(models.Model):
         blank=True,
         null=True,
         verbose_name=_('Default owner'),
+        on_delete=models.SET_NULL,
     )
 
     def __str__(self):

requirements.txt

@@ -1,4 +1,4 @@
-Django>=1.11
+Django==1.11
 django-bootstrap-form>=3.1,<4
 email-reply-parser
 django-markdown-deux