| 1 | # Contributing |
| 2 | |
| 3 | Thanks for helping with last30days. Most PRs here are opened by coding agents following [`AGENTS.md`](AGENTS.md); this file is the short path for humans and agents alike. |
| 4 | |
| 5 | ## Setup |
| 6 | |
| 7 | Python **3.12+**. From the repo root: |
| 8 | |
| 9 | ```bash |
| 10 | uv sync --group dev |
| 11 | uv run pytest |
| 12 | ``` |
| 13 | |
| 14 | That installs pytest/coverage and **towncrier** into the project env. You do **not** need a global towncrier install for normal contributions. |
| 15 | |
| 16 | ## Day-to-day PRs (no towncrier CLI) |
| 17 | |
| 18 | 1. Make your change and add/update tests. |
| 19 | 2. If it should show up in the next release notes, add a fragment: |
| 20 | ```bash |
| 21 | # Prefer the PR or issue number when you know it: |
| 22 | # changelog.d/<number>.<type>.md |
| 23 | # Orphan (no number yet): |
| 24 | # changelog.d/+short-slug.<type>.md |
| 25 | ``` |
| 26 | Types: `added`, `changed`, `fixed`, `removed`, `deprecated`, `security`. |
| 27 | Details: [`changelog.d/README.md`](changelog.d/README.md). |
| 28 | 3. Fill out [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md) — Summary (“what does this PR do”), Testing, Changelog, Agent disclosure, Relationship. |
| 29 | 4. Do **not** edit `CHANGELOG.md` and do **not** bump version strings in `pyproject.toml`, `SKILL.md`, plugin/marketplace JSON, or `uv.lock`. CI enforces that. |
| 30 | |
| 31 | Chores with nothing for the release notes: check Skip changelog in the template and add the `skip-changelog` label. |
| 32 | |
| 33 | Fragments are plain Markdown files. **towncrier is only used when cutting a release** (locally via `uv run` or in GitHub Actions) — contributors never run it for a feature PR. |
| 34 | |
| 35 | ## Releases (maintainers) |
| 36 | |
| 37 | Prefer **Actions → Prepare release** (patch / minor / major). That opens a lockstep version PR (towncrier builds `CHANGELOG.md`, bumps every plugin/marketplace surface). Merging to `main` tags `vX.Y.Z` and the existing Release workflow publishes artifacts. |
| 38 | |
| 39 | Local equivalent (after `uv sync --group dev`): |
| 40 | |
| 41 | ```bash |
| 42 | uv run python .github/scripts/prepare_release.py --bump patch # or --version X.Y.Z |
| 43 | ``` |
| 44 | |
| 45 | More detail: `AGENTS.md` § Changelog and releases, and `docs/solutions/workflow-issues/towncrier-lockstep-release.md`. |
| 46 | |
| 47 | ## Tests |
| 48 | |
| 49 | ```bash |
| 50 | uv run pytest |
| 51 | uv run pytest tests/test_dedupe_v3.py -k some_case |
| 52 | uv run pytest --cov |
| 53 | ``` |
| 54 | |
| 55 | ## Security |
| 56 | |
| 57 | Never commit real API keys, cookies, tokens, or `.env` contents. Use dummy values in tests and fixtures. |
| 58 |