Skip to content

Commit af28e76

Browse files
docs: address Gemini review findings on release procedure
- Clarify `.patch` slot is reserved for Python-only fixes (upstream patches sync via minor bump, so no collision) - Document `verify_test_fidelity.py` needs `$TS_ROOT` (else silently passes — a release-blocking foot-gun) - Mark deprecated releases instead of deleting them (preserve history, avoid breaking external links) - Tighten "no alpha for sync releases" wording so it doesn't contradict the `0.4.26a1` example in the version-scheme section
1 parent a2673b5 commit af28e76

1 file changed

Lines changed: 16 additions & 3 deletions

File tree

CONTRIBUTING.md

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -58,16 +58,26 @@ All PRs must pass `ruff check` with zero errors.
5858
Vercel Chat version. See [UPSTREAM_SYNC.md](docs/UPSTREAM_SYNC.md#version-mapping).
5959

6060
- `0.4.25` = synced to upstream `4.25.0`
61-
- `0.4.25.1` = Python-only fix
61+
- `0.4.25.1` = Python-only fix on top of `4.25.0`
6262
- `0.4.26a1` = alpha while porting upstream `4.26.0`
6363

64+
> **Upstream patch releases**: Vercel Chat has historically gone straight to
65+
> minor bumps, but if upstream ships a patch (e.g. `4.25.1`) we sync it by
66+
> bumping to the next minor (`0.4.26`). We don't reuse the `.patch` slot for
67+
> upstream patches — it's reserved for Python-only fixes so the two can't
68+
> collide.
69+
6470
### Steps
6571

6672
1. **Full validation** (must all pass):
6773
```bash
6874
uv run ruff check src/ tests/ scripts/
6975
uv run ruff format --check src/ tests/ scripts/
7076
uv run python scripts/audit_test_quality.py
77+
# verify_test_fidelity.py needs the upstream TS repo at $TS_ROOT (default
78+
# /tmp/vercel-chat). Without it, the script silently skips checks and exits
79+
# 0, so releases can ship unverified. Clone once:
80+
# git clone https://github.com/vercel/chat.git /tmp/vercel-chat
7181
uv run python scripts/verify_test_fidelity.py
7282
uv run pytest tests/ --tb=short -q
7383
```
@@ -97,13 +107,16 @@ Vercel Chat version. See [UPSTREAM_SYNC.md](docs/UPSTREAM_SYNC.md#version-mappin
97107

98108
6. **Verify on PyPI**: `pip install chat-sdk=={version}`
99109

100-
7. **Cleanup**: delete any yanked/superseded GitHub releases.
110+
7. **Cleanup**: mark yanked/superseded GitHub releases as deprecated in their
111+
description — don't delete them (deleting removes history and breaks any
112+
external links that reference the tag).
101113

102114
### What NOT to do
103115

104116
- Don't publish without CI green on all 4 Python versions (3.10-3.13)
105117
- Don't skip the fidelity check for test changes
106-
- Don't use alpha tags for upstream syncs (only for work-in-progress)
118+
- Don't use alpha tags for *final* sync releases — alpha tags (`0.4.26a1`) are
119+
only for work-in-progress ports while syncing a new upstream version
107120
- Don't amend published releases — create a patch instead
108121

109122
## License

0 commit comments

Comments
 (0)