Contributing

It is recommended that contributions to this project are created within vscode, utilising the devcontainer functionality.

This ensures that all developers are using the same environment and extentions, reducing the risk of additional bugs / formatting issues within the project.

Note

The setup of VSCode devcontainer is outside of the scope of this document additional information can be found within the VSCode documentation.

Setup your environment

  1. Fork the repository

  2. Open the repository in VSCode

  3. Press ctrl + shift + p and select Remote-Container: Open repository in Container

  4. type in <yourusername>/asyncpow (or whateve you named the repository)

  5. The environment should clone to a docker container and load the devcontainer

Updating AsyncPOW module

Style & formatting

It is highly recommended to use vsCode devcontainer as this automatically adds the required formatting checks on pre-commit, this will allow for resolution of issues prior to the pull request being submitted.

If you are not using devcontainer please register the pre-commit-config:

poetry run pre-commit install

A few guidelines for approval:

  • Must follow PEP8 / Black formatting. (devcontainer is setup to reformat on save)

  • We recommend using sourcery to ensure code is most efficient, this will be checked when the pull request is opened.

  • All functions must use google docstring format, the devcontainer has an

    autodocstring plugin which will auto fill.

  • Each feature / bugfix etc. should have its own pull request.

Testing

Tests can be run with the following command: nox -s tests. This command will check code style and typing compliance and will then execute all required``tests``

If you are adding a new method to the library, a test must be added as well. This test should be against the live API, if a mock is required then reason for this should be added to the PR notes.

Updating Documentation

The documentation for this project utilises sphinx. Sphinx allows for automatic documenting of all classes / functions via DocString.

To Update static pages, you can amend the .rst files in the docs folder.

To test the documentation locally use command nox -s docs this will create all HTML files in the build directory.

All Python Class / Function documentation is updated automatically by Github Actions and does not require any manual changes to be made.

Sphinx documentation uses reStructuredText to format each of the pages.

Pull Requests & Release

Now that you have made the changes required for your enhancement, a pull request is required for the core team to review the changes, request amendments or approve the work that you have completed.

Pull Requests

  • Each feature / bugfix should have its own PR. This makes code review more efficient

    and allows for a clean changelog generation

  • All CI tests must be passing

  • If a Pull Request contains multiple changes, our core team may reject it

  • All information in the Pull Request template should be completed, when people look

    at what was done with this Pull Request it should be easy to tell from this template

  • It must state if the change is a Breaking Change, and what would break by implementing

Release Changes

Releases are completed automatically by Python-semantic-release.

If the only change is to documentation, the workflow Sphinx Documentation Update will be run to update the documentation.

Documentation updates don’t require the version to be updated in pyproject.toml and also don’t require tagging.