Release 0.2.0: graduation merge race fix + VITE_APP_NAME + versioning infrastructure
- Fix §13.3 step 4 race against Gitea's async mergeability computation: gitea.wait_for_mergeable polls the mergeable field before calling merge, and bot._merge_with_retry rides out the transient 'Please try again later' response. - Frontend now requires VITE_APP_NAME at build time (frontend/vite.config.js fails the build if unset). Header brand, landing H1, and browser title read the deployment's configured name. - Establish framework versioning: VERSION (canonical) + frontend/package.json#version mirror; CHANGELOG.md as the release log with RFC 2119 / 8174 normative-language upgrade-steps; SPEC.md §20 as the binding policy; CLAUDE.md capturing the separation-of-concerns rule; docs/DEPLOYMENTS.md as the downstream operating manual; docs/QUICKSTART-VISION.md staking the future one-command-deploy capability. - Surgical fix to SPEC.md opening so the spec no longer asserts OHM is the corpus the framework produces. - SPEC.md §19.2 gains the 'Deployment-supplied subject framing' candidate that drives the 0.3.0 release.
This commit is contained in:
@@ -0,0 +1,93 @@
|
||||
# Changelog
|
||||
|
||||
The binding policy for what each kind of version bump means and what
|
||||
the changelog has to carry is in [`SPEC.md` §20](./SPEC.md). The
|
||||
practical recipe downstream deployments follow when reading this file
|
||||
is in [`docs/DEPLOYMENTS.md`](./docs/DEPLOYMENTS.md).
|
||||
|
||||
The canonical version is the `VERSION` file at the repo root;
|
||||
`frontend/package.json#version` mirrors it. Deployments pin to a
|
||||
specific framework version in their own `.rfc-app-version` file
|
||||
(per §20.5).
|
||||
|
||||
While the framework is pre-1.0, minor-version bumps may introduce
|
||||
breaking changes; the entry below each such bump documents the
|
||||
upgrade steps a deployment must apply.
|
||||
|
||||
Upgrade-steps blocks use the [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119)
|
||||
/ [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174) normative-
|
||||
language convention per `SPEC.md` §20.4. **MUST** / **SHALL** steps
|
||||
are required; **SHOULD** steps are recommended (the framework's
|
||||
default and tested path); **MAY** steps are optional. Upgrades that
|
||||
skip versions are the composition of each intervening adjacent
|
||||
release's steps in order — no A-to-B path is pre-computed beyond
|
||||
that.
|
||||
|
||||
## 0.2.0 — 2026-05-26
|
||||
|
||||
**Breaking config change.** The frontend now requires
|
||||
`VITE_APP_NAME` to be set at build time. `npm run build` fails with a
|
||||
clear message if it is missing. There is no default; every deployment
|
||||
names itself.
|
||||
|
||||
### Upgrade steps (from 0.1.0)
|
||||
|
||||
1. The deployment **MUST** create a `frontend/.env` file before
|
||||
building. See `frontend/.env.example` for the contract.
|
||||
2. The deployment **MUST** set `VITE_APP_NAME` in `frontend/.env` to
|
||||
the user-visible name it wants to ship — the string used as the
|
||||
browser tab title, the header brand, and the landing H1. The
|
||||
build will fail loudly if this is unset or blank.
|
||||
3. The deployment **MUST** rebuild the frontend (`npm install && npm
|
||||
run build`) and redeploy the resulting bundle. The previous
|
||||
bundle does not read `VITE_APP_NAME`.
|
||||
4. The deployment **SHOULD** verify the name appears correctly in
|
||||
the browser tab and the header after redeploy before bumping its
|
||||
`.rfc-app-version` pin to `0.2.0`.
|
||||
5. The deployment **MAY**, in the same upgrade, take the opportunity
|
||||
to retire any local overrides it was using to brand the
|
||||
pre-0.2.0 hardcoded strings — those overrides are now obsolete.
|
||||
6. The deployment **MUST NOT** continue to expect graduation step 4
|
||||
to fail on Gitea's "Please try again later" race; that path is
|
||||
now handled by `wait_for_mergeable` + bounded retry. Any local
|
||||
workaround retrying graduation at the deployment level is now
|
||||
redundant and **SHOULD** be removed.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Graduation merge race.** §13.3 step 4 (`merge_pr`) used to call
|
||||
Gitea's merge endpoint the instant step 3 returned, which races
|
||||
Gitea's background mergeability computation and produces the
|
||||
`405 "Please try again later"` response. Step 4 now waits for the
|
||||
`mergeable` field to become non-null (bounded by a 30s timeout) and
|
||||
retries the merge call up to three times on the transient response.
|
||||
See `backend/app/gitea.py#wait_for_mergeable` and
|
||||
`backend/app/bot.py#_merge_with_retry`.
|
||||
|
||||
### Changed
|
||||
|
||||
- `frontend/src/App.jsx` header brand reads `VITE_APP_NAME` instead of
|
||||
a hardcoded string.
|
||||
- `frontend/src/components/Landing.jsx` H1 reads `VITE_APP_NAME`
|
||||
instead of a hardcoded string. The pitch / deck / attribution copy
|
||||
in this file is still deployment-specific and tracked as a follow-up
|
||||
for extraction into deployment config.
|
||||
- `frontend/index.html` `<title>` is rewritten at build time via Vite's
|
||||
HTML transform.
|
||||
|
||||
### Added
|
||||
|
||||
- `frontend/.env.example` documenting the new required variable.
|
||||
- Top-level `VERSION` file and this `CHANGELOG.md` as the canonical
|
||||
release log.
|
||||
- `SPEC.md` §20 (versioning and downstream deployments) as the
|
||||
binding policy for the framework/deployment relationship.
|
||||
- `docs/DEPLOYMENTS.md` as the practical guide for building on
|
||||
rfc-app and upgrading existing deployments to new versions.
|
||||
- `CLAUDE.md` at the repo root capturing the separation-of-concerns
|
||||
rule for working sessions.
|
||||
|
||||
## 0.1.0 — v1 build
|
||||
|
||||
Initial release. See `docs/DEV.md` for the slicing plan and build
|
||||
history.
|
||||
Reference in New Issue
Block a user