Contributing
============

flask-restx is open-source and very open to contributions.

If you're part of a corporation with an NDA, and you may require updating the license.
See Updating Copyright below

Submitting issues
-----------------

Issues are contributions in a way so don't hesitate
to submit reports on the `official bugtracker`_.

Provide as much informations as possible to specify the issues:

- the flask-restx version used
- a stacktrace
- installed applications list
- a code sample to reproduce the issue
- ...


Submitting patches (bugfix, features, ...)
------------------------------------------

If you want to contribute some code:

1. fork the `official flask-restx repository`_
2. Ensure an issue is opened for your feature or bug
3. create a branch with an explicit name (like ``my-new-feature`` or ``issue-XX``)
4. do your work in it
5. Commit your changes. Ensure the commit message includes the issue. Also, if contributing from a corporation, be sure to add a comment with the Copyright information
6. rebase it on the master branch from the official repository (cleanup your history by performing an interactive rebase)
7. add your change to the changelog
8. submit your pull-request
9. 2 Maintainers should review the code for bugfix and features. 1 maintainer for minor changes (such as docs)
10. After review, a maintainer a will merge the PR. Maintainers should not merge their own PRs

There are some rules to follow:

- your contribution should be documented (if needed)
- your contribution should be tested and the test suite should pass successfully
- your code should be properly formatted (use ``black .`` to format)
- your contribution should support both Python 2 and 3 (use ``tox`` to test)

You need to install some dependencies to develop on flask-restx:

.. code-block:: console

    $ pip install -e .[dev]

An `Invoke <https://www.pyinvoke.org/>`_ ``tasks.py`` is provided to simplify the common tasks:

.. code-block:: console

    $ inv -l
    Available tasks:

      all      Run tests, reports and packaging
      assets   Fetch web assets -- Swagger. Requires NPM (see below)
      clean    Cleanup all build artifacts
      cover    Run tests suite with coverage
      demo     Run the demo
      dist     Package for distribution
      doc      Build the documentation
      qa       Run a quality report
      test     Run tests suite
      tox      Run tests against Python versions

To ensure everything is fine before submission, use ``tox``.
It will run the test suite on all the supported Python version
and ensure the documentation is generating.

.. code-block:: console

    $ tox

You also need to ensure your code is compliant with the flask-restx coding standards:

.. code-block:: console

    $ inv qa

To ensure everything is fine before committing, you can launch the all in one command:

.. code-block:: console

    $ inv qa tox

It will ensure the code meet the coding conventions, runs on every version on python
and the documentation is properly generating.

.. _official flask-restx repository: https://github.com/python-restx/flask-restx
.. _official bugtracker: https://github.com/python-restx/flask-restx/issues

Running a local Swagger Server
------------------------------

For local development, you may wish to run a local server. running the following will install a swagger server

.. code-block:: console

    $ inv assets

NOTE: You'll need `NPM <https://docs.npmjs.com/getting-started/>`_ installed to do this.
If you're new to NPM, also check out `nvm <https://github.com/creationix/nvm/blob/master/README.md>`_

Release process
---------------

The new releases are pushed on `Pypi.org <https://pypi.org/>`_ automatically
from `GitHub Actions <https://github.com/python-restx/flask-restx/actions?query=workflow%3ARelease>`_ when we add a new tag (unless the
tests are failing).

In order to prepare a new release, you can use `bumpr <https://github.com/noirbizarre/bumpr>`_
which automates a few things.
You first need to install it, then run the ``bumpr`` command. You can then refer
to the `documentation <https://bumpr.readthedocs.io/en/latest/commandline.html>`_
for further details.
For instance, you would run ``bumpr -m`` (replace ``-m`` with ``-p`` or ``-M``
depending the expected version).

Updating Copyright
------------------

If you're a part of a corporation with an NDA, you may be required to update the
LICENSE file. This should be discussed and agreed upon by the project maintainers.

1. Check with your legal department first.
2. Add an appropriate line to the LICENSE file.
3. When making a commit, add the specific copyright notice.

Double check with your legal department about their regulations. Not all changes
constitute new or unique work.
