Skip to content

Latest commit

 

History

History
125 lines (72 loc) · 3.26 KB

CONTRIBUTING.rst

File metadata and controls

125 lines (72 loc) · 3.26 KB
Raw

Contributing Guide

Contributions are welcome and greatly appreciated!

Workflow

A bug-fix or enhancement is delivered using a pull request. A good pull request should cover one bug-fix or enhancement feature. This ensures the change set is easier to review and less likely to need major re-work or even be rejected.

The workflow that developers typically use to fix a bug or add enhancements is as follows.

  • Fork the approx repo into your account.

  • Obtain the source by cloning it onto your development machine.

    $ git clone git@github.com:your_name_here/approx.git
$ cd approx

  • Create a branch for local development:

    $ git checkout -b name-of-your-bugfix-or-feature

    Now you can make your changes locally.

  • Familiarize yourself with the developer convenience rules in the Makefile.

    $ make help

  • Create and activate a Python virtual environment for local development.

    $ make venv
$ source path/to/<venv-name>/bin/activate
(venv) $

    The rule creates the virtual environment outside the project directory so that it never accidentally gets added to the change set.

    Note

    (venv) is used to indicate when the commands should be run within the virtual environment containing the development dependencies.

  • Develop fix or enhancement:

    • Make a fix or enhancement (e.g. modify a class, method, function, module, etc).

    • Update an existing unit test or create a new unit test module to verify the change works as expected.

    • Run the test suite.

      (venv) $ make test

      See the :ref:`testing-label` section for more information on testing.

    • Check code coverage of the area of code being modified.

      (venv) $ make check-coverage

      Review the output produced in docs/source/coverage/coverage.html. Add additional test steps, where practical, to improve coverage.

    • The change should be style compliant. Perform style check.

      (venv) $ make check-style

      See the :ref:`style-compliance-label` section for more information.

    • The change should include type annotations where appropriate. Perform type annotations check.

      (venv) $ make check-types

      See the :ref:`annotations-label` section for more information.

    • Fix any errors or regressions.

  • The docs and the change log should be updated for anything but trivial bug fixes. Perform docs check.

    (venv) $ make docs

    See the :ref:`documentation-label` section for more information.

  • Commit and push changes to your fork.

    $ git add .
$ git commit -m "A detailed description of the changes."
$ git push origin name-of-your-bugfix-or-feature

    A pull request should preferably only have one commit upon the current master HEAD, (via rebases and squash).

  • Submit a pull request through the service website (e.g. Github, Gitlab).

  • Check automated continuous integration steps all pass. Fix any problems if necessary and update the pull request.