Skip to content

Commit eecd041

Browse files
lesnik512claude
andcommitted
docs(release): design for 0.1.0 release prep
Decisions: - Delete CHANGELOG.md (modern-di convention; release notes on GitHub Releases). - Add .github/workflows/publish.yml mirroring modern-di's release flow. - Trim README.md to ship only what's actually shipped (drop the Retry/ RetryBudget/Bulkhead/Timeout/Observability/OTel bullets until those Epics land). Status banner explicitly names the unshipped categories. - pyproject.toml version stays "0"; publish recipe overrides with `uv version $GITHUB_REF_NAME`. - Tag format: bare 0.1.0 (no v prefix), matching modern-di. Out of scope: production code changes, mkdocs site (Epic 6), Trusted Publishers / Sigstore release flow (Story 6-5). Includes the manual post-merge sequence (PyPI name verification, secret check, GitHub Release create) — those execute by the maintainer after the prep PR merges. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 204d463 commit eecd041

1 file changed

Lines changed: 261 additions & 0 deletions

File tree

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
# Release 0.1.0 prep (design)
2+
3+
- **Date:** 2026-05-31
4+
- **Status:** approved, ready for plan
5+
- **Scope:** Prep the repository for the first PyPI release (`0.1.0` alpha). Single PR delivers all repo-side edits; the GitHub Release that triggers the publish workflow is a separate manual action by the maintainer. Out of scope: writing user docs site (Epic 6), Trusted Publishers / Sigstore release flow (Story 6-5), feature work toward v1.0.
6+
- **Why now:** Epic 1 is complete (PRs #1–#13). The middleware foundation (2-1/2-2/2-3) is shipped. `AsyncClient` is the working public surface. Users can do meaningful work with the current API; further iteration benefits from real consumer feedback. Modern-di-style alpha release model: tag now, iterate, no CHANGELOG file (release notes live on GitHub Releases).
7+
8+
## Decisions
9+
10+
| Decision | Choice |
11+
| --- | --- |
12+
| Release model | Alpha. `0.1.0` declares the API in flux until v1.0; minor releases may break things. Matches modern-di's pre-1.0 posture. |
13+
| CHANGELOG.md | **Delete.** modern-di in the same org doesn't have one. Release notes live on GitHub Releases (one entry per tag). |
14+
| README.md | Strict trim: only document what actually ships. Remove the resilience-middleware / observability / OTel bullets. Add an explicit "what's not yet shipped" line under the status banner. |
15+
| pyproject.toml | Untouched. `version = "0"` stays as the placeholder; the publish recipe overrides via `uv version $GITHUB_REF_NAME`. |
16+
| Tag format | Bare `0.1.0` (no `v` prefix). Matches modern-di. |
17+
| Publish workflow | Add `.github/workflows/publish.yml` mirroring modern-di's. Triggered by `release: published`. Runs `just publish`. |
18+
| Justfile | Untouched. `just publish` already does `rm -rf dist && uv version $GITHUB_REF_NAME && uv build && uv publish --token $PYPI_TOKEN`. |
19+
| PyPI name | Must verify ownership of `httpware` on PyPI before tagging. The package URL returns HTTP 200; check via `pypi.org/pypi/httpware/json` whether the owner is `modern-python` (our project) or a third party. |
20+
| Engineering.md roadmap | Unchanged for this PR. Adding "Released" markers is a tiny follow-up commit (not in scope here). |
21+
| Out-of-scope feature work | None added in this PR. The repo ships what's already on `main` at `204d463`. |
22+
23+
## What ships in 0.1.0 — public surface
24+
25+
| Symbol | Import |
26+
| --- | --- |
27+
| `AsyncClient` | `from httpware import AsyncClient` |
28+
| `Request`, `Response`, `StreamResponse` | `from httpware import Request, Response, StreamResponse` |
29+
| `Limits`, `Timeout`, `ClientConfig` | `from httpware import Limits, Timeout, ClientConfig` |
30+
| `Transport`, `Httpx2Transport`, `RecordedTransport` | `from httpware import …` |
31+
| `ResponseDecoder`, `PydanticDecoder` | `from httpware import ResponseDecoder, PydanticDecoder` |
32+
| `MsgspecDecoder` | `from httpware.decoders.msgspec import MsgspecDecoder` (gated by `[msgspec]` extra) |
33+
| `Middleware`, `Next` | `from httpware import Middleware, Next` |
34+
| `before_request`, `after_response`, `on_error` | `from httpware import …` |
35+
| Exception hierarchy | `from httpware import StatusError, TransportError, TimeoutError, ClientError, ServerStatusError, ClientStatusError, STATUS_TO_EXCEPTION, BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitedError, InternalServerError, ServiceUnavailableError` |
36+
37+
Behind the seam: `httpware._internal.chain.compose`, `httpware._internal.import_checker`.
38+
39+
## What 0.1.0 does NOT ship
40+
41+
- `auth=` parameter on `AsyncClient` (Story 2-4).
42+
- `data=` / `files=` body params on HTTP methods.
43+
- Transport reference-counting on `with_options` views.
44+
- Retry / timeout / bulkhead / RetryBudget middleware (Epic 3).
45+
- Streaming (`AsyncClient.stream`) — `StreamResponse` is a placeholder stub (Epic 4).
46+
- Observability hooks / OpenTelemetry middleware (Epic 5).
47+
- `niquests` transport (declared as an extra but not yet implemented).
48+
- User documentation site (mkdocs / readthedocs — Epic 6).
49+
- Migration guide from `community-of-python/base-client` (Story 6-1).
50+
- Public benchmark suite (Story 6-3).
51+
- CI enforcement gates beyond what's currently in `ci.yml` (Story 6-4).
52+
- Trusted Publishers + Sigstore release flow (Story 6-5; we use the simpler token-based publish for now).
53+
- CHANGELOG.md.
54+
55+
## Edits in the prep PR
56+
57+
**Deleted files:**
58+
- `CHANGELOG.md` — release notes live on GitHub Releases going forward.
59+
60+
**New files:**
61+
- `.github/workflows/publish.yml` — mirrors modern-di. Triggered by `release: published`, runs `just publish`. Reads `PYPI_TOKEN` from repo secrets.
62+
63+
**Modified files:**
64+
- `README.md` — strict trim per Section 2 of the brainstorm. Remove the "Highlights" bullets for unshipped features. Update the status banner to name the unshipped categories (resilience middleware, streaming, observability). Drop the CHANGELOG link.
65+
- `CONTRIBUTING.md` — check for and remove any reference to `CHANGELOG.md`. If the existing CONTRIBUTING doesn't mention it, no change needed.
66+
- `CLAUDE.md` — same check; remove `CHANGELOG.md` references if present.
67+
68+
**Files NOT touched:**
69+
- `pyproject.toml` — `version = "0"` stays; publish recipe overrides.
70+
- `Justfile` — `publish` recipe already correct.
71+
- `.github/workflows/ci.yml` — no changes to test/lint matrix.
72+
- `src/httpware/**` — no code changes.
73+
- `tests/**` — no test changes.
74+
- `LICENSE`, `SECURITY.md` — unchanged.
75+
- `docs/engineering.md` — internal roadmap stays; "Released" markers are a follow-up.
76+
- `docs/archive/**` — bmad archive untouched.
77+
78+
## `.github/workflows/publish.yml` content
79+
80+
```yaml
81+
name: Publish Package
82+
83+
on:
84+
release:
85+
types:
86+
- published
87+
88+
jobs:
89+
publish:
90+
runs-on: ubuntu-latest
91+
steps:
92+
- uses: actions/checkout@v4
93+
- uses: extractions/setup-just@v2
94+
- uses: astral-sh/setup-uv@v3
95+
- run: just publish
96+
env:
97+
PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
98+
```
99+
100+
Byte-for-byte identical to modern-di's `publish.yml`. No customization needed.
101+
102+
## README.md content (final)
103+
104+
```markdown
105+
# httpware
106+
107+
[![Test](https://github.com/modern-python/httpware/actions/workflows/ci.yml/badge.svg)](https://github.com/modern-python/httpware/actions/workflows/ci.yml)
108+
[![PyPI version](https://badge.fury.io/py/httpware.svg)](https://pypi.org/project/httpware/)
109+
[![Python versions](https://img.shields.io/pypi/pyversions/httpware.svg)](https://pypi.org/project/httpware/)
110+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
111+
112+
**Async HTTP client framework for Python.**
113+
114+
`httpware` is a typed, async HTTP client library built on `httpx2` with a protocol-based seam so the transport is swappable. Middleware composes via an onion model. Pydantic and msgspec response decoding ship out of the box. `RecordedTransport` replaces respx for transport-level tests.
115+
116+
> **Status:** Pre-1.0 (0.1.0 alpha). Public API is subject to change between minor releases until v1.0. Resilience middleware (retry / timeout / bulkhead), streaming, and observability are not yet shipped — track progress on GitHub.
117+
118+
## Install
119+
120+
\`\`\`bash
121+
pip install httpware
122+
\`\`\`
123+
124+
Optional extras:
125+
126+
\`\`\`bash
127+
pip install httpware[msgspec] # MsgspecDecoder
128+
\`\`\`
129+
130+
(`otel`, `niquests`, and `all` extras are declared but their integrations have not shipped yet.)
131+
132+
## Quickstart
133+
134+
\`\`\`python
135+
from httpware import AsyncClient
136+
from pydantic import BaseModel
137+
138+
139+
class User(BaseModel):
140+
id: int
141+
name: str
142+
143+
144+
async def main() -> None:
145+
async with AsyncClient(base_url="https://api.example.com") as client:
146+
user = await client.get("/users/1", response_model=User)
147+
print(user.name)
148+
\`\`\`
149+
150+
## What ships in 0.1.0
151+
152+
- **`AsyncClient`** — eight HTTP method shortcuts (`get`, `post`, `put`, `patch`, `delete`, `head`, `options`, `request`) with typed `response_model` overloads; per-call overrides for `headers`, `params`, `cookies`, `timeout`, `json`, `content`; httpx-style `base_url` join; `with_options(...)` returns a view sharing the same transport.
153+
- **Transport-agnostic seam.** `httpx2` is confined to `httpware.transports.httpx2.Httpx2Transport`. Implement the `Transport` protocol to swap backends.
154+
- **Middleware foundation.** `Middleware` protocol, `Next` type alias, recursive-closure `compose()` chain composition, and phase decorators (`@before_request`, `@after_response`, `@on_error`).
155+
- **Pluggable response decoding.** `PydanticDecoder` (default) with cached `TypeAdapter`; `MsgspecDecoder` via `httpware[msgspec]`.
156+
- **`RecordedTransport`** — built-in test double with a route table, observed-request list, and `aclose_calls` counter.
157+
- **Status-keyed exception hierarchy** — `StatusError`, 4xx / 5xx subclasses, plain typed fields (`status: int`, `body: bytes`, `headers`, `json`, `request_method`, `request_url`). Pickleable; userinfo redacted in `__repr__`.
158+
- **No `httpx2` exception types** leak through `httpware`. The transport seam maps them to `httpware` exceptions.
159+
160+
## Part of `modern-python`
161+
162+
Browse the full list of templates and libraries in [`modern-python`](https://github.com/modern-python) — see the org profile for the categorized index.
163+
164+
## License
165+
166+
MIT — see [LICENSE](./LICENSE).
167+
```
168+
169+
The triple-backticks above use backslash-escapes in this spec because the spec itself is markdown; in the actual `README.md` they're real triple-backticks.
170+
171+
## Release execution (post-merge, manual maintainer actions)
172+
173+
These steps are NOT part of the PR. They run after the prep PR merges to `main`.
174+
175+
1. **Verify PyPI name ownership:**
176+
177+
```bash
178+
curl -s https://pypi.org/pypi/httpware/json \
179+
| python -c "import sys, json; d=json.load(sys.stdin); info=d.get('info', {}); print('home:', info.get('home_page')); print('project_urls:', info.get('project_urls')); print('author:', info.get('author'))"
180+
```
181+
182+
Decision tree:
183+
- Homepage / project_urls point to `github.com/modern-python/httpware` → name is ours, proceed.
184+
- Different owner → STOP. Rename or open a PyPI name-transfer request. Don't tag.
185+
- Returns 404 → name is free, proceed.
186+
187+
2. **Verify `PYPI_TOKEN` secret exists on the repo:**
188+
189+
```bash
190+
gh secret list --repo modern-python/httpware | grep PYPI_TOKEN
191+
```
192+
193+
If absent, add it via `gh secret set PYPI_TOKEN --repo modern-python/httpware` with a PyPI account token scoped to the `httpware` project.
194+
195+
3. **Create the GitHub Release (triggers publish workflow):**
196+
197+
```bash
198+
gh release create 0.1.0 \
199+
--title "0.1.0 — initial alpha" \
200+
--notes-file - <<'EOF'
201+
Initial public alpha of `httpware`.
202+
203+
**Includes:**
204+
- AsyncClient with 8 HTTP method shortcuts and typed `response_model` overloads
205+
- Transport-agnostic seam (`httpx2` confined to `Httpx2Transport`)
206+
- Middleware foundation: `Middleware` protocol, `compose()`, phase decorators
207+
- Pluggable response decoders: `PydanticDecoder` (default), `MsgspecDecoder` via `[msgspec]` extra
208+
- `RecordedTransport` test double
209+
- Status-keyed exception hierarchy
210+
211+
**Not yet shipped (next releases):**
212+
- Resilience middleware (retry, timeout, bulkhead) — Epic 3
213+
- Streaming (`AsyncClient.stream`) — Epic 4
214+
- Observability / OpenTelemetry — Epic 5
215+
- `auth=` parameter on AsyncClient — Story 2-4
216+
- `data=` / `files=` body params
217+
218+
Public API is subject to change between minor releases until v1.0.
219+
EOF
220+
```
221+
222+
The release publication triggers `publish.yml` → `just publish` → `uv version 0.1.0 && uv build && uv publish --token`. The workflow's status appears in the Actions tab.
223+
224+
4. **Smoke-check the published package:**
225+
226+
```bash
227+
# In a fresh venv:
228+
pip install httpware==0.1.0
229+
python -c "import httpware; from httpware import AsyncClient, Middleware, RecordedTransport; print('OK:', httpware.__file__)"
230+
```
231+
232+
Expected: `OK: …/site-packages/httpware/__init__.py`. If import fails or names are missing, a `0.1.1` patch follows the same release cycle.
233+
234+
## Constraints and invariants
235+
236+
- **No production code changes.** This PR ships only documentation and CI workflow edits.
237+
- **No `httpx2` import added.** `tests/test_no_httpx2_leakage.py` keeps passing.
238+
- **`just lint-ci` keeps passing.** ruff, ty, eof-fixer all clean.
239+
- **`just test` keeps passing.** 273 tests at 100% line coverage on the source.
240+
241+
## Risks and mitigations
242+
243+
| Risk | Mitigation |
244+
| --- | --- |
245+
| PyPI name `httpware` is owned by someone else. | The maintainer verifies via the PyPI JSON API before tagging. If owned, stop and rename or transfer. No code-level change anticipated for this case. |
246+
| `PYPI_TOKEN` secret missing. | `gh secret list` check before tagging; add via `gh secret set` if absent. |
247+
| The publish workflow fails mid-build (e.g., `uv build` error on a CI runner that differs from local). | The tag stays; the workflow can be re-run from the Actions tab. If a content change is needed, a `0.1.1` follow-up tag publishes the fix. The repo doesn't accumulate state from a failed publish. |
248+
| Users install 0.1.0 and try to use `Retry` / `Timeout` / OTel middleware (which aren't shipped). | README's status banner names the unshipped categories explicitly. Each feature's import would fail loudly (`ImportError`), not silently. |
249+
| Documentation site URL (`https://httpware.readthedocs.io`) referenced in pyproject.toml doesn't resolve. | Keep the URL as a forward-pointer (matches modern-di which has the same pattern). Users see the broken link; not a release blocker. Epic 6's mkdocs site lights it up later. |
250+
| Renaming the package later (if PyPI name is contested) is disruptive. | The maintainer verifies name ownership BEFORE any consumer can depend on the published name. The 0.1.0 wheel never lands on PyPI unless the name is ours. |
251+
252+
## Definition of done
253+
254+
- `CHANGELOG.md` deleted.
255+
- `.github/workflows/publish.yml` exists with the modern-di-pattern content.
256+
- `README.md` updated to the trimmed content from Section 2 of the brainstorm / the README block above.
257+
- `CONTRIBUTING.md` and `CLAUDE.md` checked for `CHANGELOG.md` references; updated if any were present.
258+
- `just test` and `just lint-ci` clean.
259+
- `tests/test_no_httpx2_leakage.py` still passes.
260+
- PR `chore/release-0.1.0-prep` lands on `main` via merge.
261+
- Post-merge actions (PyPI name check, secret verification, GitHub Release creation) execute successfully; `0.1.0` lands on PyPI; `pip install httpware==0.1.0` works in a clean venv.

0 commit comments

Comments
 (0)