2011-02-25 23:48:40 +01:00
|
|
|
Contributing
|
|
|
|
|
============
|
|
|
|
|
|
2017-02-16 01:59:59 +01:00
|
|
|
django-helpdesk is an open-source project and as such contributions from the
|
2017-03-20 08:19:53 +01:00
|
|
|
community are welcomed and encouraged!
|
|
|
|
|
|
|
|
|
|
Please read these guidelines to get up to speed quickly. If you have any
|
|
|
|
|
questions, please file an issue ticket on GitHub. Our main project
|
|
|
|
|
repository is available at:
|
|
|
|
|
|
|
|
|
|
https://github.com/django-helpdesk/django-helpdesk
|
2011-02-25 23:48:40 +01:00
|
|
|
|
|
|
|
|
Licensing
|
|
|
|
|
---------
|
|
|
|
|
|
2017-09-13 03:16:30 +02:00
|
|
|
All contributions to django-helpdesk *must* be under the BSD license documented
|
|
|
|
|
in the LICENSE file in the top-level directory of this project.
|
2017-03-20 08:19:53 +01:00
|
|
|
|
|
|
|
|
By submitting a contribution to this project (in any way: via e-mail,
|
2017-09-13 03:16:30 +02:00
|
|
|
via GitHub pull requests, ticket attachments, etc), you acknowledge that your
|
|
|
|
|
contribution is open-source and licensed under the BSD license.
|
2011-02-25 23:48:40 +01:00
|
|
|
|
2017-02-16 01:59:59 +01:00
|
|
|
If you or your organisation does not accept these license terms then we cannot
|
|
|
|
|
accept your contribution. Please reconsider!
|
2011-02-25 23:48:40 +01:00
|
|
|
|
2017-09-13 03:16:30 +02:00
|
|
|
Ways to Contribute
|
|
|
|
|
------------------
|
2011-02-25 23:48:40 +01:00
|
|
|
|
2017-09-13 03:16:30 +02:00
|
|
|
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
|
2011-02-25 23:48:40 +01:00
|
|
|
|
2017-09-13 03:16:30 +02:00
|
|
|
More details on each of theses tasks is below.
|
2011-02-25 23:48:40 +01:00
|
|
|
|
2017-09-13 03:16:30 +02:00
|
|
|
If you have any questions on contributing, please start a discussion on
|
|
|
|
|
the GitHub issue tracker at
|
2011-02-25 23:48:40 +01:00
|
|
|
|
2017-09-13 03:16:30 +02:00
|
|
|
https://github.com/django-helpdesk/django-helpdesk/issues
|
2012-08-08 07:21:29 +02:00
|
|
|
|
2017-09-13 03:16:30 +02:00
|
|
|
### Back-end Python/Django
|
2011-02-25 23:48:40 +01:00
|
|
|
|
2017-09-13 03:16:30 +02:00
|
|
|
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.
|
2011-02-25 23:48:40 +01:00
|
|
|
|
2017-02-16 01:59:59 +01:00
|
|
|
Wherever possible please break git commits up into small chunks that are
|
2017-09-13 03:16:30 +02:00
|
|
|
specific to a single bit of functionality. For example, a commit should *not*
|
2017-02-16 01:59:59 +01:00
|
|
|
contain both new functionality *and* a bugfix; the new function and the bugfix
|
|
|
|
|
should be separate commits wherever possible.
|
2011-02-25 23:48:40 +01:00
|
|
|
|
|
|
|
|
Commit messages should also explain *what*, precisely, has been changed.
|
|
|
|
|
|
2017-02-16 01:59:59 +01:00
|
|
|
All commits should include appropriate new or updated tests; see the Tests
|
|
|
|
|
section below for more details.
|
2017-02-11 05:20:59 +01:00
|
|
|
|
2017-09-13 03:16:30 +02:00
|
|
|
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.
|
2011-04-27 11:57:03 +02:00
|
|
|
|
2017-09-13 03:16:30 +02:00
|
|
|
#### Tests
|
2012-08-08 07:21:29 +02:00
|
|
|
|
2017-02-16 01:59:59 +01:00
|
|
|
Currently, test coverage is very low. We're working on increasing this, and to
|
2017-09-13 03:16:30 +02:00
|
|
|
make life easier we are using Travis CI (http://travis-ci.org/) for continuous
|
2017-02-16 01:59:59 +01:00
|
|
|
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.
|
2017-02-11 05:20:59 +01:00
|
|
|
|
2017-02-16 01:59:59 +01:00
|
|
|
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.
|
2017-02-11 05:20:59 +01:00
|
|
|
|
2017-02-16 01:59:59 +01:00
|
|
|
More significant code refactoring must also include proper integration or
|
2017-09-13 03:16:30 +02:00
|
|
|
validation tests, to be committed *BEFORE* the refactoring patches. This is to
|
2017-02-16 01:59:59 +01:00
|
|
|
ensure that the refactored code produces the same results as the previous code
|
|
|
|
|
base.
|
2017-02-11 05:20:59 +01:00
|
|
|
|
2017-02-16 01:59:59 +01:00
|
|
|
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.
|
2012-08-08 07:21:29 +02:00
|
|
|
|
|
|
|
|
Please include tests in the ``tests/`` folder when committing code changes.
|
|
|
|
|
|
2017-02-16 01:59:59 +01:00
|
|
|
If you have any questions about creating or maintaining proper tests, please
|
|
|
|
|
start a discussion on the GitHub issue tracker at
|
2017-02-11 05:20:59 +01:00
|
|
|
|
|
|
|
|
https://github.com/django-helpdesk/django-helpdesk/issues
|
2012-08-08 07:21:29 +02:00
|
|
|
|
2017-09-13 03:16:30 +02:00
|
|
|
#### Database schema changes
|
2011-04-27 11:57:03 +02:00
|
|
|
|
2017-02-16 01:59:59 +01:00
|
|
|
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::
|
2011-04-27 11:57:03 +02:00
|
|
|
|
|
|
|
|
./manage.py migrate helpdesk --auto [migration_name]
|
|
|
|
|
|
2017-02-16 01:59:59 +01:00
|
|
|
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*.
|
2011-04-27 11:57:03 +02:00
|
|
|
|
2017-02-16 01:59:59 +01:00
|
|
|
This will add a file to the ``migrations/`` folder, which must be committed to
|
|
|
|
|
git with your other code changes.
|
2017-09-13 03:16:30 +02:00
|
|
|
|
|
|
|
|
### Translations
|
|
|
|
|
|
|
|
|
|
Although django-helpdesk has originally been written for the English language,
|
|
|
|
|
there are already multiple translations to Spanish, Polish, German and Russian.
|
|
|
|
|
More translations are welcomed!
|
|
|
|
|
|
|
|
|
|
Translations are handled using the excellent Transifex service which is much
|
|
|
|
|
easier for most users than manually editing .po files. It also allows
|
|
|
|
|
collaborative translation. If you want to help translate django-helpdesk into
|
|
|
|
|
languages other than English, we encourage you to make use of our Transifex
|
|
|
|
|
project:
|
|
|
|
|
|
|
|
|
|
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.
|
