Skip to content

Latest commit

 

History

History
110 lines (71 loc) · 3.2 KB

CONTRIBUTING.adoc

File metadata and controls

110 lines (71 loc) · 3.2 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

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 https://tox.readthedocs.io/en/latest/[tox].

Run the full test suite with

    tox

And linting with

    tox -e lint

Optional, but recommended, linting setup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

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