1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
|
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.
|
