Contributing to the Globus SDK

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

The globus-sdk is developed in a public GitHub repo.

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

Installing a Development Environment

To install the development environment (virtualenv and pre-commit hooks) in a new repo, run

make install

To update an install for an existing development environment, e.g., after updating the dependency list, run

make clean && make install

Linting & Testing

Testing the SDK requires tox.

Run the full test suite with

tox

And linting with

tox -e lint

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.)

  • 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.