Skip to content

Latest commit

 

History

History
252 lines (168 loc) · 6.67 KB

CONTRIBUTING.rst

File metadata and controls

252 lines (168 loc) · 6.67 KB
Raw

Contributing

Thank you for your interest! Sanic is always looking for contributors. If you don't feel comfortable contributing code, adding docstrings to the source files is very appreciated.

We are committed to providing a friendly, safe and welcoming environment for all, regardless of gender, sexual orientation, disability, ethnicity, religion, or similar personal characteristic. Our code of conduct sets the standards for behavior.

Installation

To develop on sanic (and mainly to just run the tests) it is highly recommend to install from sources.

So assume you have already cloned the repo and are in the working directory with a virtual environment already set up, then run:

pip3 install -e . ".[dev]"

Dependency Changes

Sanic doesn't use requirements*.txt files to manage any kind of dependencies related to it in order to simplify the effort required in managing the dependencies. Please make sure you have read and understood the following section of the document that explains the way sanic manages dependencies inside the setup.py file.

Dependency Type Usage Installation
requirements Bare minimum dependencies required for sanic to function pip3 install -e .
tests_require / extras_require['test'] Dependencies required to run the Unit Tests for sanic pip3 install -e '.[test]'
extras_require['dev'] Additional Development requirements to add contributing pip3 install -e '.[dev]'
extras_require['docs'] Dependencies required to enable building and enhancing sanic documentation pip3 install -e '.[docs]'

Running all tests

To run the tests for Sanic it is recommended to use tox like so:

tox

See it's that simple!

tox.ini contains different environments. Running tox without any arguments will run all unittests, perform lint and other checks.

Run unittests

tox environment -> [testenv]

To execute only unittests, run tox with environment like so:

tox -e py36 -v -- tests/test_config.py
# or
tox -e py37 -v -- tests/test_config.py

Run lint checks

tox environment -> [testenv:lint]

Permform flake8, black and isort checks.

tox -e lint

Run other checks

tox environment -> [testenv:check]

Perform other checks.

tox -e check

Run Static Analysis

tox environment -> [testenv:security]

Perform static analysis security scan

tox -e security

Run Documentation sanity check

tox environment -> [testenv:docs]

Perform sanity check on documentation

tox -e docs

Code Style

To maintain the code consistency, Sanic uses following tools.

  1. isort
  2. black
  3. flake8

isort

isort sorts Python imports. It divides imports into three categories sorted each in alphabetical order.

  1. built-in
  2. third-party
  3. project-specific

black

black is a Python code formatter.

flake8

flake8 is a Python style guide that wraps following tools into one.

  1. PyFlakes
  2. pycodestyle
  3. Ned Batchelder's McCabe script

isort, black and flake8 checks are performed during tox lint checks.

Refer tox documentation for more details.

Pull requests

So the pull request approval rules are pretty simple:

  1. All pull requests must have a changelog details associated with it.
  2. All pull requests must pass unit tests.
  3. All pull requests must be reviewed and approved by at least one current collaborator on the project.
  4. All pull requests must pass flake8 checks.
  5. All pull requests must be consistent with the existing code.
  6. If you decide to remove/change anything from any common interface a deprecation message should accompany it.
  7. If you implement a new feature you should have at least one unit test to accompany it.
  8. An example must be one of the following:
    • Example of how to use Sanic
    • Example of how to use Sanic extensions
    • Example of how to use Sanic and asynchronous library

Changelog

It is mandatory to add documentation for Change log as part of your Pull request when you fix/contribute something to the sanic community. This will enable us in generating better and well defined change logs during the release which can aid community users in a great way.

Note

Single line explaining the details of the PR in brief

Detailed description of what the PR is about and what changes or enhancements are being done. No need to include examples or any other details here. But it is important that you provide enough context here to let user understand what this change is all about and why it is being introduced into the sanic codebase.

Make sure you leave an line space after the first line to make sure the document rendering is clean

Contribution Type Changelog file name format Changelog file location
Features <git_issue>.feature.rst changelogs
Bugfixes <git_issue>.bugfix.rst changelogs
Improved Documentation <git_issue>.doc.rst changelogs
Deprecations and Removals <git_issue>.removal.rst changelogs
Miscellaneous internal changes <git_issue>.misc.rst changelogs

Documentation

Sanic's documentation is built using sphinx. Guides are written in Markdown and can be found in the docs folder, while the module reference is automatically generated using sphinx-apidoc.

To generate the documentation from scratch:

sphinx-apidoc -fo docs/_api/ sanic
sphinx-build -b html docs docs/_build

# There is a simple make command provided to ease the work required in generating
# the documentation
make docs

The HTML documentation will be created in the docs/_build folder.

Warning

One of the main goals of Sanic is speed. Code that lowers the performance of Sanic without significant gains in usability, security, or features may not be merged. Please don't let this intimidate you! If you have any concerns about an idea, open an issue for discussion and help.