Skip to content

Commit 6d56261

Browse files
jsignellgadomski
jsignell
and
gadomski
authored
Consolidate contributing docs into one place (#478)
* Consolidate contributing docs into one place * Update changelog * PR number not issue * docs, fix: contributing link --------- Co-authored-by: Pete Gadomski <[email protected]>
1 parent 8786fcf commit 6d56261

File tree

3 files changed

+110
-149
lines changed

3 files changed

+110
-149
lines changed

‎CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
1111

1212
- Switched to Ruff from isort/flake8 [#457](https://github.com/stac-utils/pystac-client/pull/457)
1313
- Move to `FutureWarning` from `DeprecationWarning` for item search interface functions that are to be removed [#464](https://github.com/stac-utils/pystac-client/pull/464)
14+
- Consolidate contributing docs into one place [#478](https://github.com/stac-utils/pystac-client/issues/478)
1415

1516
### Fixed
1617

‎README.md

Lines changed: 2 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@
66
[![Documentation](https://readthedocs.org/projects/pystac-client/badge/?version=latest)](https://pystac-client.readthedocs.io/en/latest/)
77
[![codecov](https://codecov.io/gh/stac-utils/pystac-client/branch/main/graph/badge.svg)](https://codecov.io/gh/stac-utils/pystac-client)
88

9-
109
A Python client for working with [STAC](https://stacspec.org/) Catalogs and APIs.
1110

1211
## Table of Contents
@@ -15,15 +14,13 @@ A Python client for working with [STAC](https://stacspec.org/) Catalogs and APIs
1514
- [Installation](#installation)
1615
- [Documentation](#documentation)
1716
- [Development](#development)
18-
- [Pull Requests](#pull-requests)
19-
- [Benchmark](#benchmark)
2017

2118
## Installation
2219

2320
Install from PyPi. Other than [PySTAC](https://pystac.readthedocs.io) itself, the only dependencies for pystac-client is the Python [requests](https://docs.python-requests.org) and [dateutil](https://dateutil.readthedocs.io) libraries.
2421

2522
```shell
26-
$ pip install pystac-client
23+
pip install pystac-client
2724
```
2825

2926
## Documentation
@@ -32,113 +29,4 @@ See the [documentation page](https://pystac-client.readthedocs.io/en/latest/) fo
3229

3330
## Development
3431

35-
For development, clone the repository and use the standard Python method for installing
36-
the library as an "editable link", then install the development dependencies:
37-
38-
```shell
39-
$ git clone https://github.com/stac-utils/pystac-client.git
40-
$ cd pystac-client
41-
$ pip install -e .
42-
$ pip install -r requirements-dev.txt
43-
```
44-
45-
[pre-commit](https://pre-commit.com/) is used to ensure a standard set of formatting and
46-
linting is run before every commit. These hooks should be installed with:
47-
48-
```shell
49-
$ pre-commit install
50-
```
51-
52-
These can then be run independent of a commit with:
53-
54-
```shell
55-
$ pre-commit run --all-files
56-
```
57-
58-
To run just the tests:
59-
60-
```shell
61-
$ pytest -v -s --block-network --cov pystac_client --cov-report term-missing
62-
```
63-
64-
The pystac-client tests use [vcrpy](https://vcrpy.readthedocs.io/en/latest/) to mock API calls
65-
with "pre-recorded" API responses. When adding new tests use the `@pytest.mark.vcr` decorator
66-
function to indicate `vcrpy` should be used. Record the new responses and commit them to the
67-
repository.
68-
69-
```shell
70-
$ pytest -v -s --record-mode new_episodes --block-network
71-
$ git add <new files here>
72-
$ git commit -a -m 'new test episodes'
73-
```
74-
75-
To update pystac-client to use future versions of STAC API, the existing recorded API responses
76-
should be "re-recorded":
77-
78-
```shell
79-
$ pytest -v -s --record-mode rewrite --block-network
80-
$ git commit -a -m 'updated test episodes'
81-
```
82-
83-
### Pull Requests
84-
85-
To make Pull Requests to pystac-client, the code must pass linting, formatting, and code tests. To run
86-
the entire suit of checks and tests that will be run the GitHub Action Pipeline, use the `test` script.
87-
88-
```shell
89-
$ scripts/test
90-
```
91-
92-
If automatic formatting is desired (incorrect formatting will cause the GitHub Action to fail),
93-
use the format script and commit the resulting files:
94-
95-
```shell
96-
$ scripts/format
97-
$ git commit -a -m 'formatting updates'
98-
```
99-
100-
To build the documentation, [install Pandoc](https://pandoc.org/installing.html), install the
101-
Python documentation requirements via pip, then use the `build-docs` script:
102-
103-
```shell
104-
$ pip install -r requirements-docs.txt
105-
$ scripts/build-docs
106-
```
107-
108-
### Benchmark
109-
110-
By default, pystac-client benchmarks are skipped during test runs.
111-
To run the benchmarks, use the `--benchmark-only` flag:
112-
113-
```shell
114-
$ pytest --benchmark-only
115-
============================= test session starts ==============================
116-
platform darwin -- Python 3.9.13, pytest-6.2.4, py-1.10.0, pluggy-0.13.1
117-
benchmark: 3.4.1 (defaults: timer=time.perf_counter disable_gc=False min_rounds=5 min_time=0.000005 max_time=1.0 calibration_precision=10 warmup=False warmup_iterations=100000)
118-
rootdir: /Users/gadomski/Code/pystac-client, configfile: pytest.ini
119-
plugins: benchmark-3.4.1, recording-0.11.0, console-scripts-1.1.0, requests-mock-1.9.3, cov-2.11.1, typeguard-2.13.3
120-
collected 75 items
121-
122-
tests/test_cli.py ss [ 2%]
123-
tests/test_client.py ssssssssssssssss [ 24%]
124-
tests/test_collection_client.py ss [ 26%]
125-
tests/test_item_search.py ...sssssssssssssssssssssssssssssssssssssssssss [ 88%]
126-
s [ 89%]
127-
tests/test_stac_api_io.py ssssssss [100%]
128-
129-
130-
--------------------------------------------------------------------------------------- benchmark: 3 tests --------------------------------------------------------------------------------------
131-
Name (time in ms) Min Max Mean StdDev Median IQR Outliers OPS Rounds Iterations
132-
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
133-
test_single_item_search 213.4729 (1.0) 284.8732 (1.0) 254.9405 (1.0) 32.9424 (3.27) 271.0926 (1.0) 58.2907 (4.95) 1;0 3.9225 (1.0) 5 1
134-
test_single_item 314.6746 (1.47) 679.7592 (2.39) 563.9692 (2.21) 142.7451 (14.18) 609.5605 (2.25) 93.9942 (7.98) 1;1 1.7731 (0.45) 5 1
135-
test_requests 612.9212 (2.87) 640.5024 (2.25) 625.6871 (2.45) 10.0637 (1.0) 625.1143 (2.31) 11.7822 (1.0) 2;0 1.5982 (0.41) 5 1
136-
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
137-
138-
Legend:
139-
Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile.
140-
OPS: Operations Per Second, computed as 1 / Mean
141-
======================== 3 passed, 72 skipped in 11.86s ========================
142-
```
143-
144-
For more information on running and comparing benchmarks, see the [pytest-benchmark documentation](https://pytest-benchmark.readthedocs.io/en/latest/).
32+
See the [contributing page](https://pystac-client.readthedocs.io/en/latest/contributing.html) for the latest development instructions.

‎docs/contributing.rst

Lines changed: 107 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -7,88 +7,160 @@ way is to coordinate with the core developers via an issue or pull request conve
77

88
Development installation
99
^^^^^^^^^^^^^^^^^^^^^^^^
10-
Fork PySTAC-Client into your GitHub account. Then, clone the repo and install
11-
it locally with pip as follows:
10+
Fork PySTAC Client into your GitHub account. Clone the repo, install
11+
the library as an "editable link", then install the development dependencies:
1212

1313
.. code-block:: bash
1414
1515
$ git clone [email protected]:your_user_name/pystac-client.git
1616
$ cd pystac
1717
$ pip install -e .
18+
$ pip install -r requirements-dev.txt
1819
1920
Testing
2021
^^^^^^^
21-
PySTAC-Client runs tests using ``unittest``. You can find unit tests in the ``tests/``
22+
tl;dr: Run ``./scripts/test`` to run all tests and linters.
23+
24+
PySTAC Client runs tests using `pytest <https://docs.pytest.org/en/latest/>`_. You can find unit tests in the ``tests/``
2225
directory.
2326

24-
Run a single test with:
27+
To run the tests and generate the coverage report:
2528

2629
.. code-block:: bash
2730
28-
python -m unittest tests/test_catalog.py
31+
$ pytest -v -s --block-network --cov pystac_client --cov-report term-missing
2932
30-
or an entire folder using:
33+
The PySTAC Client tests use `vcrpy <https://vcrpy.readthedocs.io/en/latest/>`_ to mock API calls
34+
with "pre-recorded" API responses. When adding new tests use the ``@pytest.mark.vcr`` decorator
35+
function to indicate ``vcrpy`` should be used. Record the new responses and commit them to the
36+
repository.
3137

3238
.. code-block:: bash
3339
34-
python -m unittest discover -v -s tests/
40+
$ pytest -v -s --record-mode new_episodes
41+
$ git add <new files here>
42+
$ git commit -a -m 'new test episodes'
3543
36-
or the entire project using:
3744
38-
.. code-block:: bash
45+
To update PySTAC Client to use future versions of STAC API, the existing recorded API responses
46+
should be "re-recorded":
3947

40-
./scripts/test
48+
.. code-block:: bash
4149
42-
The last command will also check test coverage. To view the coverage report, you can run
43-
`coverage report` (to view the report in the terminal) or `coverage html` (to generate
44-
an HTML report that can be opened in a browser).
50+
$ pytest -v -s --record-mode rewrite --block-network
51+
$ git commit -a -m 'updated test episodes'
4552
46-
More details on using ``unittest`` are `here
47-
<https://docs.python.org/3/library/unittest.html>`_.
4853
4954
Code quality checks
5055
^^^^^^^^^^^^^^^^^^^
5156

52-
tl;dr: Run ``pre-commit install --overwrite`` to perform checks when committing, and
53-
``./scripts/test`` to run the tests.
57+
`pre-commit <https://pre-commit.com/>`_ is used to ensure a standard set of formatting and
58+
linting is run before every commit. These hooks should be installed with:
59+
60+
.. code-block:: bash
61+
62+
$ pre-commit install
5463
55-
PySTAC-Client uses
64+
These can then be run independent of a commit with:
65+
66+
.. code-block:: bash
67+
68+
$ pre-commit run --all-files
69+
70+
PySTAC Client uses
5671

5772
- `black <https://github.com/psf/black>`_ for Python code formatting
5873
- `codespell <https://github.com/codespell-project/codespell/>`_ to check code for common misspellings
59-
- `doc8 <https://github.com/pycqa/doc8>`__ for style checking on RST files in the docs
74+
- `doc8 <https://github.com/pycqa/doc8>`_ for style checking on RST files in the docs
6075
- `ruff <https://beta.ruff.rs/docs/>`_ for Python style checks
6176
- `mypy <http://www.mypy-lang.org/>`_ for Python type annotation checks
6277

63-
Run all of these with ``pre-commit run --all-files`` or a single one using
64-
``pre-commit run --all-files ID``, where ``ID`` is one of the command names above. For
65-
example, to format all the Python code, run ``pre-commit run --all-files black``.
66-
67-
You can also install a Git pre-commit hook which will run the relevant linters and
68-
formatters on any staged code when committing. This will be much faster than running on
69-
all files, which is usually [#]_ only required when changing the pre-commit version or
70-
configuration. Once installed you can bypass this check by adding the ``--no-verify``
78+
Once installed you can bypass pre-commit by adding the ``--no-verify`` (or ``-n``)
7179
flag to Git commit commands, as in ``git commit --no-verify``.
7280

73-
.. [#] In rare cases changes to one file might invalidate an unchanged file, such as
74-
when modifying the return type of a function used in another file.
81+
Pull Requests
82+
^^^^^^^^^^^^^
83+
84+
To make Pull Requests to PySTAC Client, the code must pass linting, formatting, and code tests. To run
85+
the entire suit of checks and tests that will be run the GitHub Action Pipeline, use the ``test`` script.
86+
87+
.. code-block:: bash
88+
89+
$ scripts/test
90+
91+
If automatic formatting is desired (incorrect formatting will cause the GitHub Action to fail),
92+
use the format script and commit the resulting files:
93+
94+
.. code-block:: bash
95+
96+
$ scripts/format
97+
$ git commit -a -m 'formatting updates'
98+
99+
100+
To build the documentation, `install Pandoc <https://pandoc.org/installing.html>`_, install the
101+
Python documentation requirements via pip, then use the ``build-docs`` script:
102+
103+
.. code-block:: bash
104+
105+
$ pip install -r requirements-docs.txt
106+
$ scripts/build-docs
75107
76108
CHANGELOG
77109
^^^^^^^^^
78110

79-
PySTAC-Client maintains a
80-
`changelog <https://github.com/stac-utils/pystac-client/blob/main/CHANGELOG.md>`__
81-
to track changes between releases. All PRs should make a changelog entry unless
111+
PySTAC Client maintains a
112+
`changelog <https://github.com/stac-utils/pystac-client/blob/main/CHANGELOG.md>`_
113+
to track changes between releases. All Pull Requests should make a changelog entry unless
82114
the change is trivial (e.g. fixing typos) or is entirely invisible to users who may
83115
be upgrading versions (e.g. an improvement to the CI system).
84116

85117
For changelog entries, please link to the PR of that change. This needs to happen in a
86118
few steps:
87119

88-
- Make a PR to PySTAC-Client with your changes
89-
- Record the link to the PR
120+
- Make a Pull Request (see above) to PySTAC Client with your changes
121+
- Record the link to the Pull Request
90122
- Push an additional commit to your branch with the changelog entry with the link to the
91-
PR.
123+
Pull Request.
92124

93125
For more information on changelogs and how to write a good entry, see `keep a changelog
94126
<https://keepachangelog.com/en/1.0.0/>`_.
127+
128+
Benchmark
129+
^^^^^^^^^
130+
131+
By default, PySTAC Client benchmarks are skipped during test runs.
132+
To run the benchmarks, use the ``--benchmark-only`` flag:
133+
134+
.. code-block:: bash
135+
136+
$ pytest --benchmark-only
137+
============================= test session starts ==============================
138+
platform darwin -- Python 3.9.13, pytest-6.2.4, py-1.10.0, pluggy-0.13.1
139+
benchmark: 3.4.1 (defaults: timer=time.perf_counter disable_gc=False min_rounds=5 min_time=0.000005 max_time=1.0 calibration_precision=10 warmup=False warmup_iterations=100000)
140+
rootdir: /Users/gadomski/Code/pystac-client, configfile: pytest.ini
141+
plugins: benchmark-3.4.1, recording-0.11.0, console-scripts-1.1.0, requests-mock-1.9.3, cov-2.11.1, typeguard-2.13.3
142+
collected 75 items
143+
144+
tests/test_cli.py ss [ 2%]
145+
tests/test_client.py ssssssssssssssss [ 24%]
146+
tests/test_collection_client.py ss [ 26%]
147+
tests/test_item_search.py ...sssssssssssssssssssssssssssssssssssssssssss [ 88%]
148+
s [ 89%]
149+
tests/test_stac_api_io.py ssssssss [100%]
150+
151+
152+
--------------------------------------------------------------------------------------- benchmark: 3 tests --------------------------------------------------------------------------------------
153+
Name (time in ms) Min Max Mean StdDev Median IQR Outliers OPS Rounds Iterations
154+
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
155+
test_single_item_search 213.4729 (1.0) 284.8732 (1.0) 254.9405 (1.0) 32.9424 (3.27) 271.0926 (1.0) 58.2907 (4.95) 1;0 3.9225 (1.0) 5 1
156+
test_single_item 314.6746 (1.47) 679.7592 (2.39) 563.9692 (2.21) 142.7451 (14.18) 609.5605 (2.25) 93.9942 (7.98) 1;1 1.7731 (0.45) 5 1
157+
test_requests 612.9212 (2.87) 640.5024 (2.25) 625.6871 (2.45) 10.0637 (1.0) 625.1143 (2.31) 11.7822 (1.0) 2;0 1.5982 (0.41) 5 1
158+
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
159+
160+
Legend:
161+
Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile.
162+
OPS: Operations Per Second, computed as 1 / Mean
163+
======================== 3 passed, 72 skipped in 11.86s ========================
164+
165+
166+
For more information on running and comparing benchmarks, see the `pytest-benchmark documentation <https://pytest-benchmark.readthedocs.io/en/latest/>`_.

0 commit comments

Comments
 (0)