Skip to content

Latest commit

 

History

History
81 lines (53 loc) · 2.33 KB

CONTRIBUTING.adoc

File metadata and controls

81 lines (53 loc) · 2.33 KB
Raw

Contributing to the Globus SDK

First off, thank you so much for taking the time to contribute! 👍

Bugs & Feature Requests

Should be reported as GitHub Issues

For a good bug report:

  • Check if there’s a matching issue before opening a new issue

  • Provide a code sample to reproduce bugs

Linting & Testing

Testing the SDK requires tox.

Run tests with

tox

And linting with

tox -e lint

Optional, but recommended, linting setup

For the best development experience, we recommend setting up linting and autofixing integrations with your editor and git.

The Globus SDK uses pre-commit to automatically run linters and fixers. Install pre-commit and then run

$ pre-commit install

to setup the hooks.

The configured linters and fixers can be seen in .pre-commit-config.yaml.

Contributing Documentation

Documentation for the SDK is built with Sphinx and docs are written as reStructuredText in the docs/ directory.

If you want to look at local documentation, run tox -e docs and the output will be in docs/_build/dirhtml/.

Code Guidelines

These are recommendations for contributors:

  • Include tests for any new or changed functionality

  • Use type annotations liberally

  • New features should be documented via Sphinx

Code Style

Style guidance which doesn’t get handled by linters and fixers:

  • If a docstring contains special characters like \\, consider using a raw string to ensure it renders correctly

  • Use the * marker for keyword-only arguments for any signatures which take keyword arguments. (For an explanation, see [PEP 3102](https://peps.python.org/pep-3102/).)

  • Avoid use of **kwargs to capture arbitrary keyword arguments. Instead, always define a named dict argument for any open extension points (see query_params for prior art in the SDK, or extra in logging for a case from the stdlib). This makes type checking more effective and avoids a class of backwards compatibility issues when arguments are added.