Skip to content

CONTRIBUTING.adoc

Latest commit

 

History

History
99 lines (65 loc) · 2.98 KB

CONTRIBUTING.adoc

File metadata and controls

99 lines (65 loc) · 2.98 KB

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.

Writing changelog fragments

If you are contributing a significant change — e.g., a new feature — it’s best to include a changelog fragment which documents the change. This will be included in the next SDK release’s changelog. Changelog fragments are written using scriv.

First, make sure you have scriv installed with toml support, for example:

$ pipx install 'scriv[toml]'

Then use scriv create --edit to create a changelog fragment. Comments in the template should give you further guidance.

Not all changes need a changelog! If it’s a minor tweak (e.g., a doc typo), we’ll label the PR to skip our changelog requirement.

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.