Contributing to the Globus SDK
==============================

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

Bugs & Feature Requests
-----------------------

Should be reported as
https://github.com/globus/globus-sdk-python/issues[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 https://tox.readthedocs.io/en/latest/[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  https://pre-commit.com/[`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 https://www.sphinx-doc.org/[Sphinx] and
docs are written as https://docutils.sourceforge.io/rst.html[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.
