mirror of
https://github.com/django-helpdesk/django-helpdesk.git
synced 2024-12-12 18:00:45 +01:00
We require specifically Django 1.11.x, update documentation
This commit is contained in:
Garret Wassermann
parent
612a743069
commit
a5d5ef0bc5
165
CONTRIBUTING.rst
165
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.
|
||||
|
||||
53
README.rst
53
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.
|
||||
|
||||
@ -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*
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
Django>=1.11
|
||||
Django=1.11
|
||||
django-bootstrap-form>=3.1,<4
|
||||
email-reply-parser
|
||||
django-markdown-deux
|
||||
|
||||
Loading…
Reference in New Issue
Block a user