From a5d5ef0bc5a36a89dd0e11af8d4040d05e2fe663 Mon Sep 17 00:00:00 2001 From: Garret Wassermann Date: Tue, 12 Sep 2017 21:16:30 -0400 Subject: [PATCH] We require specifically Django 1.11.x, update documentation --- CONTRIBUTING.rst | 165 ++++++++++++++++++++++++++--------------------- README.rst | 53 ++++++++------- demo/README.rst | 4 +- requirements.txt | 2 +- 4 files changed, 127 insertions(+), 97 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 53182db0..1b81569a 100644 --- a/CONTRIBUTING.rst +++ b/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 -the LICENSE file in the top-level directory of this project. +All contributions to django-helpdesk *must* be under the BSD license documented +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 -open-source and licensed under the BSD license. +via GitHub pull requests, ticket attachments, etc), you acknowledge that your +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. diff --git a/README.rst b/README.rst index 9fbe07ab..062d8b2a 100644 --- a/README.rst +++ b/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: -http://docs.djangoproject.com/en/dev/ref/databases/#sqlite-string-matching +For more information, see [this note in the Django documentation](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+. -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 -transitioning to Python 3 if have not already. +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` +and Django itself (Django 2.0), so users and developers are encouraged to begin +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 -python/django code development, front-end web development -(HTML/Javascript, especially jQuery), or even language translations. +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 -For more information on contributing, please see the CONTRIBUTING.rst file. +For more information on contributing, please see the `CONTRIBUTING.rst` file. diff --git a/demo/README.rst b/demo/README.rst index 14bcfd0d..52d980bd 100644 --- a/demo/README.rst +++ b/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* diff --git a/requirements.txt b/requirements.txt index 0b95046e..7b9b0192 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ -Django>=1.11 +Django=1.11 django-bootstrap-form>=3.1,<4 email-reply-parser django-markdown-deux