You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: sdk/planetarycomputer/azure-planetarycomputer/CONTRIBUTING.md
+27-9Lines changed: 27 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -77,12 +77,24 @@ The code generator already produces a file-level suppression on line 1 of each `
77
77
| `from collections.abc import MutableMapping` | `# pylint: disable=import-error` | Not resolvable in the pylint virtualenv |
78
78
| `return super().__new__(cls)` (in `Model.__new__`) | `# pylint: disable=no-value-for-parameter` | False positive - pylint cannot resolve the MRO for `__new__` |
79
79
80
-
> **Important:** After adding pylint suppressions, run `tox -e black` first - Black may reformat single-line imports into multi-line, which moves your `# pylint: disable` comments. If Black reformats the `_deserialize_xml` import into multiple lines, the `# pylint: disable=unused-import` comment must be on the `from ... import (` line, **not** on the closing `)` or the individual name line.
80
+
> **Critical: Run Black _before_ adding pylint suppressions.** Black reformats imports (turning single-line into multi-line), which changes where `# pylint: disable` comments must go. If you add suppressions first and then run Black, the comments may end up on the wrong line. The correct order is: (1) run `tox -e black`, (2) restore tests/samples, (3) add pylint suppressions.
81
81
82
-
### Sample Updates
82
+
> **Emitter version variability:** The emitter may add different inline suppressions to different functions. For example, `build_data_get_mosaics_tile_json_request` gets the full `too-many-locals,too-many-branches,too-many-statements`, while `build_data_get_mosaics_tile_request` only gets `too-many-locals`. Always check the pylint output to see if additional suppressions are needed beyond what the emitter provides.
83
+
84
+
### Sphinx Docstring Fixes
85
+
86
+
The code generator sometimes produces RST formatting bugs in docstrings (e.g., code block terminators merged with following text, incorrect bullet continuation indentation). These must be fixed in **both** sync and async `_operations.py`. Run `tox -e sphinx` after each regeneration — Sphinx treats warnings as errors, so any formatting issues will cause a build failure.
87
+
88
+
### Sample and Test Updates
83
89
84
90
If the TypeSpec renames or removes API operations, the hand-written samples under `samples/` and `samples/async/` must be updated to match. MyPy and Pyright (which also check samples) will catch these as type errors.
85
91
92
+
**Test updates require special care:**
93
+
94
+
- **Do NOT rename test methods** even if the SDK method they test was renamed. Test method names determine recording file paths. Renaming a test method breaks the recording lookup — only change the API call *inside* the test body.
95
+
- **Update type assertions** if an API's return type changes (e.g., from `dict` to a typed model). The test assertions must match the new return type.
96
+
- **Run tests in playback mode** (`pytest tests/ -v`) after all fixes to verify all tests pass.
97
+
86
98
---
87
99
88
100
## Local Validation
@@ -269,15 +281,21 @@ Each file has a sync and async variant (e.g., `test_00_stac_collection.py` and `
0 commit comments