116 lines
3.5 KiB
Markdown
116 lines
3.5 KiB
Markdown
|
# Contributing code
|
||
|
|
||
|
## Basic requirements and standards
|
||
|
|
||
|
- A [new ticket](http://dev.deluge-torrent.org/newticket) is required for bugs
|
||
|
or features. Search the ticket system first, to avoid filing a duplicate.
|
||
|
- Ensure code follows the [syntax and conventions](#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](https://github.com/deluge-torrent/deluge).
|
||
|
- 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](https://travis-ci.org/deluge-torrent/deluge)
|
||
|
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](http://www.python.org/dev/peps/pep-0008/) and
|
||
|
[Python Code Style](http://docs.python-guide.org/en/latest/writing/style/)
|
||
|
which is adhered to with Black formatter.
|
||
|
|
||
|
- Code '''must''' pass [flake8](https://pypi.python.org/pypi/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) or `unicode` but will only return
|
||
|
`str`. 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](http://stackoverflow.com/a/9099337/175584)
|
||
|
- Python 3 renames `unicode` to `str` type and byte strings become `bytes` 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](http://www.sphinx-doc.org/en/stable/ext/napoleon.html)
|
||
|
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
|