From d0dc7af7e0b868190a9a0f7b3e72a1b8b5bed44c Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Fri, 5 Jun 2026 14:09:45 -0500 Subject: [PATCH] Convert the contrib doc to RST; add to docs The contributing doc rendered oddly on GitHub (a bad header). To fix it and align with our existing docs, it is here converted to RST and added to the doc site build. To make it easier to jump from docs to github, a new link is added to the doc. An emoji is removed, since RST doesn't support the same emoji markup as adoc and md. No other non-formatting edits are made. --- CONTRIBUTING.adoc | 110 ------------------------------------- CONTRIBUTING.rst | 123 ++++++++++++++++++++++++++++++++++++++++++ docs/contributing.rst | 1 + docs/index.rst | 1 + 4 files changed, 125 insertions(+), 110 deletions(-) delete mode 100644 CONTRIBUTING.adoc create mode 100644 CONTRIBUTING.rst create mode 100644 docs/contributing.rst diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc deleted file mode 100644 index 06129d37..00000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,110 +0,0 @@ -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 - - -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. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 00000000..19a6affc --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,123 @@ +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 + +.. code-block:: console + + make install + +To update an install for an existing development environment, e.g., after updating the +dependency list, run + +.. code-block:: console + + make clean && make install + +Linting & Testing +----------------- + +Testing the SDK requires `tox `_. + +Run the full test suite with + +.. code-block:: console + + tox + +And linting with + +.. code-block:: console + + tox -e lint + +Optional, but recommended, linting setup +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Globus SDK uses `pre-commit `_ to automatically run linters +and fixers. Install ``pre-commit`` and then run + +.. code-block:: console + + 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: + +.. code-block:: console + + 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. diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 00000000..b6e6c69f --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1 @@ +.. include:: ../CONTRIBUTING.rst diff --git a/docs/index.rst b/docs/index.rst index 525193f6..6ae9f01e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -64,4 +64,5 @@ Table of Contents :caption: Additional Info :maxdepth: 1 + contributing license