3.6 KiB

Raw Blame History

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 document 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 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 and Python Code 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
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 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.

Verify that the documentation parses correctly with:

python setup.py build_docs

3.6 KiB Raw Blame History