blob: 20ccb820b92f5cba33a8af65d889712bfbc607c5 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
|
# 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
|
