fix: #1631: add common contribution guidelines and towncrier detail to contribution guides
Signed-off-by: Harsha Narayana <harsha2k4@gmail.com>
This commit is contained in:
Harsha Narayana
parent
a019ff61e3
commit
83864f890a
141
CONTRIBUTING.md
141
CONTRIBUTING.md
|
|
@ -1,141 +0,0 @@
|
||||||
# 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](./CONDUCT.md) 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:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
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:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
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:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
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.
|
|
||||||
```bash
|
|
||||||
tox -e lint
|
|
||||||
```
|
|
||||||
|
|
||||||
## Run other checks :
|
|
||||||
`tox` environment -> `[testenv:check]`
|
|
||||||
|
|
||||||
Perform other checks.
|
|
||||||
```bash
|
|
||||||
tox -e check
|
|
||||||
```
|
|
||||||
|
|
||||||
# Code Style
|
|
||||||
To maintain the code consistency, Sanic uses following tools.
|
|
||||||
|
|
||||||
1. [isort](https://github.com/timothycrosley/isort)
|
|
||||||
2. [black](https://github.com/python/black)
|
|
||||||
2. [flake8](https://github.com/PyCQA/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](https://tox.readthedocs.io/en/latest/index.html) documentation for more details.
|
|
||||||
|
|
||||||
## Pull requests!
|
|
||||||
|
|
||||||
So the pull request approval rules are pretty simple:
|
|
||||||
1. All pull requests must pass unit tests.
|
|
||||||
2. All pull requests must be reviewed and approved by at least
|
|
||||||
one current collaborator on the project.
|
|
||||||
3. All pull requests must pass flake8 checks.
|
|
||||||
4. All pull requests must be consistent with the existing code.
|
|
||||||
5. If you decide to remove/change anything from any common interface
|
|
||||||
a deprecation message should accompany it.
|
|
||||||
6. If you implement a new feature you should have at least one unit
|
|
||||||
test to accompany it.
|
|
||||||
7. 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
|
|
||||||
|
|
||||||
## Documentation
|
|
||||||
|
|
||||||
Sanic's documentation is built
|
|
||||||
using [sphinx](http://www.sphinx-doc.org/en/1.5.1/). 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:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sphinx-apidoc -fo docs/_api/ sanic
|
|
||||||
sphinx-build -b html docs docs/_build
|
|
||||||
```
|
|
||||||
|
|
||||||
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.
|
|
||||||
252
CONTRIBUTING.rst
Normal file
252
CONTRIBUTING.rst
Normal file
|
|
@ -0,0 +1,252 @@
|
||||||
|
|
||||||
|
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 <./CONDUCT.md>`_ 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:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. list-table::
|
||||||
|
:header-rows: 1
|
||||||
|
|
||||||
|
* - 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:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
tox -e lint
|
||||||
|
|
||||||
|
Run other checks
|
||||||
|
----------------
|
||||||
|
|
||||||
|
``tox`` environment -> ``[testenv:check]``
|
||||||
|
|
||||||
|
Perform other checks.
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
tox -e check
|
||||||
|
|
||||||
|
Run Static Analysis
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
``tox`` environment -> ``[testenv:security]``
|
||||||
|
|
||||||
|
Perform static analysis security scan
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
tox -e security
|
||||||
|
|
||||||
|
Run Documentation sanity check
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
``tox`` environment -> ``[testenv:docs]``
|
||||||
|
|
||||||
|
Perform sanity check on documentation
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
tox -e docs
|
||||||
|
|
||||||
|
|
||||||
|
Code Style
|
||||||
|
----------
|
||||||
|
|
||||||
|
To maintain the code consistency, Sanic uses following tools.
|
||||||
|
|
||||||
|
|
||||||
|
#. `isort <https://github.com/timothycrosley/isort>`_
|
||||||
|
#. `black <https://github.com/python/black>`_
|
||||||
|
#. `flake8 <https://github.com/PyCQA/flake8>`_
|
||||||
|
|
||||||
|
isort
|
||||||
|
*****
|
||||||
|
|
||||||
|
``isort`` sorts Python imports. It divides imports into three
|
||||||
|
categories sorted each in alphabetical order.
|
||||||
|
|
||||||
|
|
||||||
|
#. built-in
|
||||||
|
#. third-party
|
||||||
|
#. project-specific
|
||||||
|
|
||||||
|
black
|
||||||
|
*****
|
||||||
|
|
||||||
|
``black`` is a Python code formatter.
|
||||||
|
|
||||||
|
flake8
|
||||||
|
******
|
||||||
|
|
||||||
|
``flake8`` is a Python style guide that wraps following tools into one.
|
||||||
|
|
||||||
|
|
||||||
|
#. PyFlakes
|
||||||
|
#. pycodestyle
|
||||||
|
#. Ned Batchelder's McCabe script
|
||||||
|
|
||||||
|
``isort``\ , ``black`` and ``flake8`` checks are performed during ``tox`` lint checks.
|
||||||
|
|
||||||
|
Refer `tox <https://tox.readthedocs.io/en/latest/index.html>`_ documentation for more details.
|
||||||
|
|
||||||
|
Pull requests
|
||||||
|
-------------
|
||||||
|
|
||||||
|
So the pull request approval rules are pretty simple:
|
||||||
|
|
||||||
|
#. All pull requests must have a changelog details associated with it.
|
||||||
|
#. All pull requests must pass unit tests.
|
||||||
|
#. All pull requests must be reviewed and approved by at least one current collaborator on the project.
|
||||||
|
#. All pull requests must pass flake8 checks.
|
||||||
|
#. All pull requests must be consistent with the existing code.
|
||||||
|
#. If you decide to remove/change anything from any common interface a deprecation message should accompany it.
|
||||||
|
#. If you implement a new feature you should have at least one unit test to accompany it.
|
||||||
|
#. 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
|
||||||
|
|
||||||
|
|
||||||
|
.. list-table::
|
||||||
|
:header-rows: 1
|
||||||
|
|
||||||
|
* - 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 <http://www.sphinx-doc.org/en/1.5.1/>`_. 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:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
@ -142,4 +142,4 @@ Questions and Discussion
|
||||||
Contribution
|
Contribution
|
||||||
------------
|
------------
|
||||||
|
|
||||||
We are always happy to have new contributions. We have `marked issues good for anyone looking to get started <https://github.com/huge-success/sanic/issues?q=is%3Aopen+is%3Aissue+label%3Abeginner>`_, and welcome `questions on the forums <https://community.sanicframework.org/>`_. Please take a look at our `Contribution guidelines <https://github.com/huge-success/sanic/blob/master/CONTRIBUTING.md>`_.
|
We are always happy to have new contributions. We have `marked issues good for anyone looking to get started <https://github.com/huge-success/sanic/issues?q=is%3Aopen+is%3Aissue+label%3Abeginner>`_, and welcome `questions on the forums <https://community.sanicframework.org/>`_. Please take a look at our `Contribution guidelines <https://sanic.readthedocs.io/en/latest/sanic/contributing.html>`_.
|
||||||
|
|
|
||||||
6
changelogs/1631.doc.rst
Normal file
6
changelogs/1631.doc.rst
Normal file
|
|
@ -0,0 +1,6 @@
|
||||||
|
Documentation infrastructure changes
|
||||||
|
|
||||||
|
- Enable having a single common `CHANGELOG` file for both GitHub page and documentation
|
||||||
|
- Fix Sphinix deprecation warnings
|
||||||
|
- Fix documentation warnings due to invalid `rst` indentation
|
||||||
|
- Enable common contribution guidelines file across GitHub and documentation via `CONTRIBUTING.rst`
|
||||||
|
|
@ -1,93 +1 @@
|
||||||
Contributing
|
.. include:: ../../CONTRIBUTING.rst
|
||||||
============
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
.. code:: bash
|
|
||||||
|
|
||||||
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 | ``pip3 install -e .`` |
|
|
||||||
| | to function | |
|
|
||||||
+------------------------+-----------------------------------------------+--------------------------------+
|
|
||||||
| tests_require / | Dependencies required to run the Unit Tests | ``pip3 install -e '.[test]'`` |
|
|
||||||
| extras_require['test'] | for ``sanic`` | |
|
|
||||||
+------------------------+-----------------------------------------------+--------------------------------+
|
|
||||||
| extras_require['dev'] | Additional Development requirements to add | ``pip3 install -e '.[dev]'`` |
|
|
||||||
| | for contributing | |
|
|
||||||
+------------------------+-----------------------------------------------+--------------------------------+
|
|
||||||
| extras_require['docs'] | Dependencies required to enable building and | ``pip3 install -e '.[docs]'`` |
|
|
||||||
| | enhancing sanic documentation | |
|
|
||||||
+------------------------+-----------------------------------------------+--------------------------------+
|
|
||||||
| extras_require['all'] | Dependencies required to perform all sanic | ``pip3 install -e '.[docs]'`` |
|
|
||||||
| | development activities including documenting | |
|
|
||||||
+------------------------+-----------------------------------------------+--------------------------------+
|
|
||||||
|
|
||||||
|
|
||||||
Running tests
|
|
||||||
-------------
|
|
||||||
|
|
||||||
To run the tests for sanic it is recommended to use tox like so:
|
|
||||||
|
|
||||||
.. code:: bash
|
|
||||||
|
|
||||||
tox
|
|
||||||
|
|
||||||
See it’s that simple!
|
|
||||||
|
|
||||||
Pull requests!
|
|
||||||
--------------
|
|
||||||
|
|
||||||
So the pull request approval rules are pretty simple:
|
|
||||||
|
|
||||||
* All pull requests must pass unit tests
|
|
||||||
* All pull requests must be reviewed and approved by at least one current collaborator on the project
|
|
||||||
* All pull requests must pass flake8 checks
|
|
||||||
* If you decide to remove/change anything from any common interface a deprecation message should accompany it.
|
|
||||||
* If you implement a new feature you should have at least one unit test to accompany it.
|
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
.. code:: bash
|
|
||||||
|
|
||||||
sphinx-apidoc -fo docs/_api/ sanic
|
|
||||||
sphinx-build -b html docs docs/_build
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
.. _sphinx: http://www.sphinx-doc.org/en/1.5.1/
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue
Block a user