|
3 | 3 | Thank you for your interest in contributing to the Planet SDK for Python! This |
4 | 4 | document explains how to contribute successfully. |
5 | 5 |
|
6 | | -## Workflows |
| 6 | +## Pull Requests and Continuous Integration |
7 | 7 |
|
8 | | -### Reporting Bugs |
9 | | - |
10 | | -To report a bug, open a new issue with the 'bug' label. |
11 | | - |
12 | | -In the issue, provide the following: |
13 | | -1. Code snippet reproducing the behavior, reduced to the simplest possible case |
14 | | -1. Operating System and Python version |
15 | | -1. Installed dependencies / versions |
16 | | -1. Error traceback |
17 | | - |
18 | | -### Pull Requests |
19 | | - |
20 | | -Pull Request (PR) Requirements: |
21 | | - |
22 | | -1. Must include updates to relative documentation in docstrings and `docs` folder. See Documentation section for information on docstring formatting and building/ |
23 | | -1. Must pass all Continuous Integration (CI) checks. See below for more information on CI checks. |
24 | | - |
25 | | -1. Must have at least one approval by a planet maintainer. |
26 | | - * For Planet team, **FYI** can be used to specify cases when all that is needed is indication that changes have been noted. |
27 | | -1. Should be driven by an issue. Reference the issue in the PR. |
28 | | -1. Should be as small and focused as possible. |
| 8 | +When a Pull Request (PR) is created, the Continuous Integration (CI) runs a |
| 9 | +series of checks. Before a PR can be considered, all checks must pass. |
29 | 10 |
|
30 | 11 | The CI checks: |
31 | | - |
32 | 12 | * all tests on all supported versions of Python |
33 | | -* test coverage |
34 | 13 | * linting / formatting |
35 | | -* type annotation |
36 | 14 | * docs build successfully |
37 | 15 |
|
38 | | -To minimize the feedback loop, we have configured Nox so that it can be used to run all of the CI checks on the local machine. See the [Development Tools](#development-tools) section for information on running CI checks locally with Nox. |
39 | | - |
40 | | -### Releasing |
41 | | - |
42 | | -*Planet maintainers only* |
43 | | - |
44 | | -Releasing is a two-step process: (1) releasing on Github and test.pypi and (2) releasing to pypi. Releasing on Github will automatically trigger a release on test.pypi via a Github Action. Following manual confirmation of a successful and satisfactory release on test.py, release on pypi is triggered manually with the Github Action "Automatically Publish on TestPyPi". |
| 16 | +To minimize the feedback loop, we have configured Nox so that it can be used |
| 17 | +to run all of these checks on the local machine. See the Tools section for |
| 18 | +information on how to run Nox. |
45 | 19 |
|
46 | | -###### Step 1: Release on Github |
47 | | - |
48 | | -1. Create a PR with the following: |
49 | | - * Update `docs/CHANGELOG.md` |
50 | | - * Include added, changed, depricated or removed features and bug fixes. |
51 | | - * Sort according to importance |
52 | | - * Adhere to [Keep a Changelog](https://keepachangelog.com/) |
53 | | - * Bump version in `planet/__version__.py` |
54 | | - * Version number is determined by [Semantic Versioning](https://semver.org/spec/v2.0.0.html) |
55 | | -1. Merge the PR |
56 | | -1. Create a new github release: |
57 | | - * Set Tag to the version number specified in `planet/__version__.py` |
58 | | - * Set Release to Tag with the prefix v, aka v2.0.0-beta.1 |
59 | | - * Copy Description from the new entry in `docs/CHANGELOG.md` |
60 | | - * Select "This is a pre-release" if applicable |
61 | | - * Select "Create a discussion for this release" |
62 | | - |
63 | | -###### Step 2: Release on pypi |
64 | | - |
65 | | -1. Verify the test release on [test.pypi.org](https://test.pypi.org/project/planet/) |
66 | | -1. Run the Github Action "Publish on PyPi" |
67 | | - |
68 | | - |
69 | | -## <a name="development-tools"></a>Development Tools |
| 20 | +## Tools |
70 | 21 |
|
71 | 22 | This repository uses two primary tools for development: |
72 | 23 | * [Nox](https://nox.thea.codes/) to automate testing |
@@ -105,18 +56,6 @@ speed up the run by reusing the environment: |
105 | 56 | $ nox -r |
106 | 57 | ``` |
107 | 58 |
|
108 | | -If only one test is desired, specify it with `-s`. To only run linting: |
109 | | - |
110 | | -```console |
111 | | -$ nox -s lint |
112 | | -``` |
113 | | - |
114 | | -To determine which tests are available: |
115 | | - |
116 | | -```console |
117 | | - $ nox --list |
118 | | -``` |
119 | | - |
120 | 59 | The configuration for Nox is given in `noxfile.py`. See the Nox link above for |
121 | 60 | advanced usage. |
122 | 61 |
|
@@ -155,17 +94,6 @@ To reformat the file: |
155 | 94 | $ yapf --in-place [file] |
156 | 95 | ``` |
157 | 96 |
|
158 | | -These commands can be performed on the entire repository, when run from the repository root directory, with: |
159 | | - |
160 | | -```console |
161 | | - $ yapf --diff -r . |
162 | | -``` |
163 | | - |
164 | | -and |
165 | | - |
166 | | -```console |
167 | | - $ yapf --diff -r . |
168 | | -``` |
169 | 97 | The configuration for YAPF is given in `setup.cfg` and `.yapfignore`. |
170 | 98 | See the YAPF link above for advanced usage. |
171 | 99 |
|
@@ -203,20 +131,6 @@ To run tests on python 3.7: |
203 | 131 | $ nox -s test-3.7 |
204 | 132 | ``` |
205 | 133 |
|
206 | | -Configuration can be passed onto pytest through Nox. |
207 | | - |
208 | | -To only run tests in a specific file: |
209 | | - |
210 | | -```console |
211 | | - $ nox -s test3.7 -- tests/unit/test_http.py |
212 | | -``` |
213 | | - |
214 | | -Or to only run tests filtered by keyword: |
215 | | - |
216 | | -```console |
217 | | - $ nox -s test3.7 -- -k test__Limiter |
218 | | -``` |
219 | | - |
220 | 134 | ## Code coverage |
221 | 135 |
|
222 | 136 | To measure code coverage and see a report: |
@@ -271,8 +185,6 @@ To build and host an automatically-updated local version of the documentation: |
271 | 185 | $ nox -s watch |
272 | 186 | ``` |
273 | 187 |
|
274 | | -Copy the local url from the console output and paste it into your browser to view the live rendered docs. |
275 | | - |
276 | 188 | In addition to verifying that the documentation renders correctly locally, |
277 | 189 | the accuracy of the code examples must be verified. See Testing Documentation |
278 | 190 | below. |
|
0 commit comments