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
|
||||
------------
|
||||
|
||||
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
|
||||
============
|
||||
|
||||
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/
|
||||
.. include:: ../../CONTRIBUTING.rst
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user