Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
101 lines (65 loc) · 3.24 KB

CONTRIBUTING.md

File metadata and controls

101 lines (65 loc) · 3.24 KB
Raw

Contributing to Concourse Tools

If you find any issues/bugs in the software, please file an issue. Please provide full details of your issue, and ideally code to reproduce it.

Pull Requests

Prior to us accepting any work, you must sign the GCHQ CLA Agreement. We follow a branching strategy for handling contributions:

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/new_thing)
  3. Commit your Changes (git commit -m 'Add a new thing')
  4. Push to the Branch (git push origin feature/new_thing)
  5. Open a Pull Request

Pre-commit

Please make use of the pre-commit checks, which should be installed before any new code is committed:

$ python3 -m pip install pre-commit
$ pre-commit install

To run the checks at any time:

$ pre-commit run --all-files

Please do not add any new pre-commit checks yourself and instead raise a ticket.

Tests

Before opening a pull request, please ensure that the tests pass. To do this, run the following:

$ python3 -m unittest discover .

Tests are written with unittest and - with the exception of the example tests - do not require any additional dependencies. To run the example tests you should install the additional dependencies:

$ python3 -m pip install -r requirements-tests.txt --no-deps

Mypy

Please also run a type check with Mypy:

$ python3 -m pip install mypy
$ python3 -m mypy concoursetools

Documentation

The documentation for Concourse Tools use Sphinx. Please ensure that new features are appropriately documented before opening your pull request. To build the documentation locally, first install the dependencies:

$ python3 -m pip install -r docs/requirements.txt

Next, run the following:

$ python3 -m sphinx -b html -aE docs/source docs/build

Please also make use of the linkcheck builder:

$ python3 -m sphinx -b linkcheck docs/source docs/build  # check that all links resolve

Coding Standards and Conventions

Concourse Tools is a fully-typed library, so please ensure all functions, methods and classes are fully typed.

Concourse Tools uses Sphinx-style docstrings.

This project aims to depend only on the standard library, so contributions which add additional dependencies outside of the standard library are likely to be rejected unless absolutely necessary.

Style Guide

Concourse Tools does not have an explicit style guide outside of the pre-commit checks for enforcing PEP8 and double-quote strings. However, please ensure your code is as readable and clear as possible. Reviewers will highlight any code changes they feel is inconsistent or difficult to parse.

Please refrain from running Black over the code, as it can cause readability issues for nested statements.

Finally, please do not refactor "other people's" code when submitting a pull request.