Trevin Chow
2471ea23ce
Stop shared Unreleased edits that conflict across PRs, and cut releases via Prepare release (towncrier + every plugin/marketplace version bump) then auto-tag on merge, with agent-oriented CONTRIBUTING and PR template guidance.
58 lines
2.3 KiB
Markdown
58 lines
2.3 KiB
Markdown
# Contributing
|
|
|
|
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.
|
|
|
|
## Setup
|
|
|
|
Python **3.12+**. From the repo root:
|
|
|
|
```bash
|
|
uv sync --group dev
|
|
uv run pytest
|
|
```
|
|
|
|
That installs pytest/coverage and **towncrier** into the project env. You do **not** need a global towncrier install for normal contributions.
|
|
|
|
## Day-to-day PRs (no towncrier CLI)
|
|
|
|
1. Make your change and add/update tests.
|
|
2. If it should show up in the next release notes, add a fragment:
|
|
```bash
|
|
# Prefer the PR or issue number when you know it:
|
|
# changelog.d/<number>.<type>.md
|
|
# Orphan (no number yet):
|
|
# changelog.d/+short-slug.<type>.md
|
|
```
|
|
Types: `added`, `changed`, `fixed`, `removed`, `deprecated`, `security`.
|
|
Details: [`changelog.d/README.md`](changelog.d/README.md).
|
|
3. Fill out [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md) — Summary (“what does this PR do”), Testing, Changelog, Agent disclosure, Relationship.
|
|
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.
|
|
|
|
Chores with nothing for the release notes: check Skip changelog in the template and add the `skip-changelog` label.
|
|
|
|
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.
|
|
|
|
## Releases (maintainers)
|
|
|
|
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.
|
|
|
|
Local equivalent (after `uv sync --group dev`):
|
|
|
|
```bash
|
|
uv run python .github/scripts/prepare_release.py --bump patch # or --version X.Y.Z
|
|
```
|
|
|
|
More detail: `AGENTS.md` § Changelog and releases, and `docs/solutions/workflow-issues/towncrier-lockstep-release.md`.
|
|
|
|
## Tests
|
|
|
|
```bash
|
|
uv run pytest
|
|
uv run pytest tests/test_dedupe_v3.py -k some_case
|
|
uv run pytest --cov
|
|
```
|
|
|
|
## Security
|
|
|
|
Never commit real API keys, cookies, tokens, or `.env` contents. Use dummy values in tests and fixtures.
|