125 lines
3.6 KiB
Markdown
125 lines
3.6 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](testing.md) document 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 formatting
|
|
|
|
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].
|
|
|
|
- Code '''must''' pass [Black], [flake8] and [isort] source code checkers.
|
|
(Optionally [Pylint])
|
|
|
|
flake8 deluge
|
|
isort -rc -df deluge
|
|
pylint deluge
|
|
pylint deluge/plugins/\*/deluge/
|
|
|
|
- Using the [pre-commit] application can aid in identifying issues while
|
|
creating git commits.
|
|
|
|
#### Strings and bytes
|
|
|
|
To prevent bugs or errors in the code byte strings (`str`) must be decoded to
|
|
strings (Unicode text strings, `unicode`) on input and then encoded on output.
|
|
|
|
_Notes:_
|
|
|
|
- PyGTK/GTK+ will accept `str` (UTF-8 encoded) or `unicode` but will only return
|
|
`str`. See [GTK3 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 [supported headers][napoleon sections].
|
|
|
|
Verify that the documentation parses correctly with:
|
|
|
|
python setup.py build_docs
|
|
|
|
[pre-commit]: http://pre-commit.com/
|
|
[flake8]: https://pypi.python.org/pypi/flake8
|
|
[isort]: https://pypi.python.org/pypi/isort
|
|
[pylint]: http://www.pylint.org/
|
|
[black]: https://github.com/python/black/
|
|
[gtk3 unicode]: http://python-gtk-3-tutorial.readthedocs.org/en/latest/unicode.html
|
|
[napoleon sections]: http://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#docstring-sections
|