|
| 1 | +<!-- markdownlint-disable MD041 MD043 --> |
| 2 | +# Working on Powertools for AWS Lambda (Python) |
| 3 | + |
| 4 | +Short guide for anyone, human or coding agent, changing this repository. It points to the sources of truth instead of repeating them. Read [CONTRIBUTING.md](CONTRIBUTING.md) for the process and [docs/adr](docs/adr/README.md) for the premises behind the rules below. |
| 5 | + |
| 6 | +## Before you start |
| 7 | + |
| 8 | +- Work from an issue that a maintainer triaged. PRs on untriaged issues usually wait or get closed. |
| 9 | +- One issue, one PR. Do not bundle unrelated fixes, even small ones. |
| 10 | +- Branch from `develop`. Keep the diff limited to what the issue needs; do not reformat or "improve" code you did not have to touch. |
| 11 | + |
| 12 | +## Commands |
| 13 | + |
| 14 | +```bash |
| 15 | +make dev # uv sync, pre-commit hooks |
| 16 | +make lint # ruff format + ruff check (aws_lambda_powertools, tests, examples) |
| 17 | +make mypy # static typing, must pass |
| 18 | +uv run pytest tests/unit tests/functional/<utility> # fast loop for one utility |
| 19 | +make test # full unit + functional + performance, what CI runs |
| 20 | +make pr # everything CI checks, run it before opening the PR |
| 21 | +``` |
| 22 | + |
| 23 | +Do not run the full suite with `pytest -n auto`; collection differs between workers and it fails for reasons unrelated to your change. |
| 24 | + |
| 25 | +## What a PR needs to pass |
| 26 | + |
| 27 | +- Title follows [conventional commits](.github/semantic.yml): `fix(parameters): ...`, `feat(event_handler): ...`, `docs(...)`. Scope is the utility name. |
| 28 | +- Description contains `closes #<issue>` alone on its own line. Trailing text on that line breaks the related-issue check. |
| 29 | +- Tests for the change. A bug fix adds a test that fails on `develop` and passes with the fix. |
| 30 | +- Functional tests use the public API only, the way a customer would call it. Never test internal methods: do not call or patch private methods, do not assert on private attributes. |
| 31 | +- Existing tests are not modified or deleted unless the PR proves the old behaviour was a bug. Say so in the description. |
| 32 | +- `ruff`, `mypy` and the test suite green on Python 3.10 to 3.14. CI runs all five. |
| 33 | +- Behaviour changes update the docs page and its example under `examples/<utility>/src/`. |
| 34 | + |
| 35 | +## Things we do not do |
| 36 | + |
| 37 | +- Add a runtime dependency. Optional features go behind an extra in `pyproject.toml`; the core stays `jmespath` and `typing-extensions`. See [ADR 0007](docs/adr/0007-lean-dependencies.md). |
| 38 | +- Import heavy modules at module level. Cold start matters; import lazily inside the function or utility that needs it. See [ADR 0002](docs/adr/0002-every-millisecond-counts.md). |
| 39 | +- Ship `boto3`, `botocore` or their dependencies in the Lambda layer. See [ADR 0004](docs/adr/0004-layer-and-packaging.md). |
| 40 | +- Break or change public behaviour in a minor release. If an input we accept today is wrong, warn with `PowertoolsUserWarning` now and raise in the next major. See [ADR 0006](docs/adr/0006-zero-regression-and-compatibility.md). |
| 41 | +- Duplicate a code path to add a variant (async, a new event shape). Share the logic and keep the difference to the call site. |
| 42 | +- Change `tests/events/*.json` fixtures in a way that hides a bug. Add a new fixture instead. |
| 43 | +- Use threads, background work or anything that assumes the process outlives the invocation. See [ADR 0001](docs/adr/0001-lambda-first.md). |
| 44 | + |
| 45 | +## Verifying your change |
| 46 | + |
| 47 | +- Run the tests yourself and read the output. Do not describe runs you did not do. |
| 48 | +- If the change touches an AWS service integration (Parameters, Idempotency, Batch, Data Classes shapes, Event Handler payloads), validate it against the real service or a real event and say in the PR how you did it. Mocks prove the logic, not the contract. |
| 49 | +- If you used an AI assistant, say so in the PR. We welcome it. What we ask is the verification above, done by you. |
| 50 | + |
| 51 | +## Where things are |
| 52 | + |
| 53 | +| Need | Look at | |
| 54 | +| --- | --- | |
| 55 | +| Utility code | `aws_lambda_powertools/<utility>/` or `aws_lambda_powertools/utilities/<utility>/` | |
| 56 | +| Tests | `tests/unit/<utility>/`, `tests/functional/<utility>/`, `tests/performance/` | |
| 57 | +| Sample events | `tests/events/` | |
| 58 | +| Docs and examples | `docs/<area>/<utility>.md`, `examples/<utility>/src/` | |
| 59 | +| Project premises | `docs/adr/` | |
| 60 | +| Layer build | `layer_v3/` | |
| 61 | +| Maintainer process | [MAINTAINERS.md](MAINTAINERS.md), [docs/maintainers.md](docs/maintainers.md) | |
0 commit comments