Skip to content

Commit a3ddb36

Browse files
authored
docs: Sync CONTRIBUTING.md with recent tooling changes. (#404)
Bring the contributor guide in sync with changes landed since v0.16: - Add S110 to the active rules table (silent try/except:pass). - Add explicit preview rules section listing all 12 pycodestyle rules enabled in #400 and #402 (E203, E225, E231, E261, E262, E265, E275, E301, E302, E303, E305, W391). - Add B905 and ISC003 to the MicroPython exceptions table. - Add frozen manifest check to the CI table. - Mention both MicroPython and DAPLink firmwares in the release section. - Add line endings subsection explaining .gitattributes LF enforcement and the renormalize step for existing Windows + WSL clones. - Note that Pylance config now lives in pyproject.toml [tool.pyright].
1 parent c50a976 commit a3ddb36

1 file changed

Lines changed: 33 additions & 3 deletions

File tree

CONTRIBUTING.md

Lines changed: 33 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -75,19 +75,41 @@ The full configuration is in `pyproject.toml` (`[tool.ruff.lint]` section). The
7575
| N802, N803, N806 | PEP 8 naming: functions, arguments, and variables must be `snake_case` |
7676
| PL | Pylint (complexity thresholds: max-branches=25, max-statements=65, max-args=10) |
7777
| PERF | Perflint: performance anti-patterns |
78+
| S110 | Flake8-bandit: no silent `try/except: pass` |
7879
| SIM | Flake8-simplify: code simplification suggestions |
7980
| T20 | No `print()` in production code (excluded for examples and tests) |
8081
| RUF | Ruff-specific rules |
8182

83+
### Explicit preview rules
84+
85+
Some pycodestyle rules are in ruff's preview tier and must be enabled individually (because `explicit-preview-rules = true`). These catch formatting issues that were previously missed in PRs:
86+
87+
| Rule | Description |
88+
|------|-------------|
89+
| E203 | Whitespace before `:`, `;`, or `,` (catches `else :`) |
90+
| E225 | Missing whitespace around operator |
91+
| E231 | Missing whitespace after `,` |
92+
| E261 | At least two spaces before inline comment |
93+
| E262 | Inline comment must start with `# ` |
94+
| E265 | Block comment must start with `# ` |
95+
| E275 | Missing whitespace after keyword (catches `if(...)`) |
96+
| E301 | Blank line between methods |
97+
| E302 | Expected 2 blank lines before function/class definition |
98+
| E303 | Too many blank lines |
99+
| E305 | Expected 2 blank lines after function/class definition |
100+
| W391 | Too many newlines at end of file |
101+
82102
### MicroPython-specific exceptions
83103

84104
Some rules are ignored because MicroPython does not support the corresponding Python features:
85105

86106
| Ignored rule | Reason |
87107
|--------------|--------|
88-
| SIM105 | `contextlib.suppress` is not available in MicroPython |
108+
| B905 | `zip(strict=)` is not available in MicroPython |
109+
| ISC003 | MicroPython does not support implicit concatenation of f-strings |
89110
| PIE810 | MicroPython does not support passing tuples to `.startswith()` / `.endswith()` |
90111
| SIM101 | `isinstance()` with merged tuple arguments is unreliable in MicroPython |
112+
| SIM105 | `contextlib.suppress` is not available in MicroPython |
91113

92114
## Commit messages
93115

@@ -141,7 +163,7 @@ A dev container is available for VS Code (local Docker only, not GitHub Codespac
141163
The container also provides:
142164

143165
* **zsh + oh-my-zsh** as default shell with persistent shell history
144-
* **Pylance** configured with MicroPython STM32 stubs (no false `import machine` errors)
166+
* **Pylance** configured with MicroPython STM32 stubs via `[tool.pyright]` in `pyproject.toml` (no false `import machine` errors)
145167
* **Serial Monitor** extension for board communication
146168
* **USB passthrough** for mpremote, pyOCD, OpenOCD, and MicroPython firmware flashing (the container runs in privileged mode with `/dev/bus/usb` mounted)
147169
* **udev rules** for the DAPLink interface (auto-started on container creation)
@@ -159,6 +181,10 @@ Note: GitHub Codespaces is not supported because the container requires privileg
159181

160182
If git hooks fail because `node_modules/` is missing (for example on a fresh clone or after `make deepclean`), run `make setup` or `npm install` before committing.
161183

184+
### Line endings
185+
186+
The repository enforces **LF line endings** on all text files via `.gitattributes`. This prevents CRLF shebangs from breaking husky hooks on Windows + WSL. If you have an existing clone on Windows, run `git add --renormalize .` after pulling the `.gitattributes` change to re-normalize your working tree.
187+
162188
## Continuous Integration
163189

164190
All pull requests must pass these checks:
@@ -169,6 +195,7 @@ All pull requests must pass these checks:
169195
| Linting | `python-linter.yml` | Runs `ruff check` |
170196
| Mock tests | `tests.yml` | Runs mock driver tests |
171197
| Example validation | `tests.yml` | Validates example files syntax and imports |
198+
| Frozen manifest | `tests.yml` | Verifies every `lib/*/` driver is declared in the upstream firmware manifest |
172199

173200
## Releasing
174201

@@ -179,7 +206,10 @@ Releases are handled automatically by [semantic-release](https://semantic-releas
179206
- `BREAKING CHANGE:` in commit body → major bump (v1.0.0 → v2.0.0)
180207
- `docs:`, `style:`, `test:`, `ci:`, `chore:` → no release
181208

182-
semantic-release automatically updates `pyproject.toml`, generates `CHANGELOG.md`, creates a git tag, and publishes a GitHub release with the MicroPython firmware (`.hex` and `.bin`) attached.
209+
semantic-release automatically updates `pyproject.toml`, generates `CHANGELOG.md`, creates a git tag, and publishes a GitHub release with both firmwares attached:
210+
211+
- **MicroPython firmware**: `steami-micropython-firmware-vX.Y.Z.hex` / `.bin`
212+
- **DAPLink interface firmware**: `steami-daplink-firmware-vX.Y.Z.hex` / `.bin`
183213

184214
To force a specific version manually (override):
185215

0 commit comments

Comments
 (0)