Skip to content

Latest commit

 

History

History
90 lines (60 loc) · 2.85 KB

CONTRIBUTING.md

File metadata and controls

90 lines (60 loc) · 2.85 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

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. Although we tend to make use of future annotations (from __future__ import annotations) please continue using the typing module for all types to ensure compatibility with our documentation.

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.