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. Copy the .devcontainer/recommended-devcontainer.json files and rename the copy to devcontainer.json.

  4. Modify the mounts section as required for your environment

  5. Copy the .devcontainer/recommended-docker-compose.yml files and rename the copy to docker.compose.yml

  6. You may need to modify the volumes for your environment

  7. Press ctrl + shift + p and select Remote-Container: Reopen in Container

  8. Once loaded you can begin modification of the module or Documentation

Updating PyArr 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.

  • pyproject.toml must be updated with a new version, the new versions should

    follow semver.

  • 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 sphinx-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

To release a new version of the module or documentation updates, the core team

will take the following steps:

  1. Reviewing and testing the PR that has been submitted to ensure all requirements have been met.

  2. Tag the release in git: git tag $NEW_VERSION.

  3. Push the tag to GitHub: git push --tags origin.

  4. If all tests complete the package will be automatically released to PyPI

  5. Github Action will re-create the documentation with Sphinx

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.