3.5 KiB
Contributing code
Basic requirements and standards
- A new ticket is required for bugs or features. Search the ticket system first, to avoid filing a duplicate.
- Ensure code follows the syntax and conventions.
- Code must pass tests. See [testing.md] for information on how to run and write unit tests.
- Commit messages are informative.
Pull request process:
- Fork us on github.
- Clone your repository.
- Create a feature branch for your issue.
- Apply your changes:
- Add them, and then commit them to your branch.
- Run the tests until they pass.
- When you feel you are finished, rebase your commits to ensure a simple and informative commit log.
- Create a pull request on github from your forked repository.
- Verify that the tests run by Travis-ci are passing.
Syntax and conventions
Code formatters
We use two applications to automatically format the code to save development time. They are both run with pre-commit.
Black
- Python
Prettier
- Javascript
- CSS
- YAML
- Markdown
Common
- Line length:
79
chars. - Indent:
4 spaces
, no tabs. - All code should use
'single quotes'
.
Python
We follow PEP8 and Python Code Style which is adhered to with Black formatter.
-
Code '''must''' pass flake8 (w/[https://pypi.python.org/pypi/flake8-quotes flake8-quotes]), [https://pypi.python.org/pypi/isort isort] and [http://www.pylint.org/ Pylint] source code checkers.
flake8 deluge isort -rc -df deluge pylint deluge pylint deluge/plugins/*/deluge/
-
Using the [http://pre-commit.com/ pre-commit] app can aid in picking up issues before creating git commits.
Strings and bytes
To prevent bugs or errors in the code byte strings (str
) must be decoded to
strings (unicode strings, unicode
) on input and then encoded on output.
Notes:
- PyGTK/GTK+ will accept
str
(utf8 encoded) orunicode
but will only returnstr
. See [http://python-gtk-3-tutorial.readthedocs.org/en/latest/unicode.html GTK+ Unicode] docs. - There is a
bytearray
type which enables in-place modification of a string. See Python Bytearrays - Python 3 renames
unicode
tostr
type and byte strings becomebytes
type.
Javascript
- Classes should follow the Ext coding style.
- Class names should be in !CamelCase
- Instances of classes should use camelCase.
Path separators
- All relative path separators used within code should be converted to posix
format
/
, so should not contain\
or\\
. This is to prevent confusion when dealing with cross-platform clients and servers.
Docstrings
All new docstrings must use Napoleon Google Style with old docstrings eventually converted over.
Google Style example:
def func(arg):
"""Function purpose.
Args:
arg (type): Description.
Returns:
type: Description. If the line is too, long indent next
line with three spaces.
"""
return
See complete list of [http://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#docstring-sections supported headers].
Verify that the documentation parses correctly with:
python setup.py build_docs