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,80 @@
|
||||
# Working in rfc-app
|
||||
|
||||
This is the framework — the software that hosts an RFC standardization
|
||||
process. It is intended to power **multiple deployments**, each of which
|
||||
brands and configures itself independently. The framework is the
|
||||
substrate; the deployment is the instance.
|
||||
|
||||
## The separation-of-concerns rule
|
||||
|
||||
Code in this repo must never bake in values that belong to a specific
|
||||
deployment. That includes:
|
||||
|
||||
- The deployment's display name, tagline, or pitch copy.
|
||||
- The corpus or domain the deployment is about.
|
||||
- The deployment's URL, organization name, branding assets.
|
||||
- Any reference to the people or community running a specific instance.
|
||||
|
||||
When a value of that kind is needed in source, it goes behind
|
||||
configuration — typically a build-time `VITE_*` env var the frontend
|
||||
reads, or a backend env var the API surfaces. The framework supplies a
|
||||
loud failure path (e.g. build fails, server refuses to start) when a
|
||||
required value is missing, so a misconfigured deployment can't ship the
|
||||
wrong content silently.
|
||||
|
||||
The framework name itself (`Wiggleverse RFC`, per the founding
|
||||
documents) does appear in source — in the chat system prompt, in
|
||||
`PHILOSOPHY.md`, in `SPEC.md`. That is correct: those references are
|
||||
about *the framework*, not about any deployment. Deployment names and
|
||||
deployment content stay out.
|
||||
|
||||
If you find a hardcoded deployment-specific string in source, treat it
|
||||
as a bug to fix in the framework: make it configurable, document the
|
||||
new env var in `frontend/.env.example` or `backend/.env.example`, and
|
||||
bump the version per the rules below.
|
||||
|
||||
## Versioning
|
||||
|
||||
The binding policy is in [`SPEC.md` §20](./SPEC.md). Summary so
|
||||
working sessions don't have to reload the full section:
|
||||
|
||||
- The `VERSION` file at the repo root is the canonical version;
|
||||
`frontend/package.json#version` mirrors it. A divergence between
|
||||
the two is a spec-level bug.
|
||||
- SemVer: patch = no operator action required; minor = new
|
||||
functionality plus, while pre-1.0, breaking changes spelled out
|
||||
in the changelog; major = reserved for the first stable cut and
|
||||
afterwards for breaking changes.
|
||||
- Every release adds an entry to `CHANGELOG.md`. Breaking entries
|
||||
carry an "upgrade steps" block; a downstream deployment must be
|
||||
able to upgrade from any prior version by walking those blocks in
|
||||
order.
|
||||
|
||||
The practical recipe for downstream projects — how to pin, how to
|
||||
upgrade, how the two-repo loop runs — is in
|
||||
[`docs/DEPLOYMENTS.md`](./docs/DEPLOYMENTS.md). Don't restate that
|
||||
recipe here; if it's wrong, fix it there.
|
||||
|
||||
## How changes typically flow in
|
||||
|
||||
The framework receives change requests from deployments. The intake
|
||||
loop:
|
||||
|
||||
1. A deployment operator notices something they want different
|
||||
(different name, missing feature, wrong behavior).
|
||||
2. Triage: is this a framework concern (bug, missing affordance, hard-
|
||||
coded value that should be configurable) or a deployment concern
|
||||
(just a config value to change)?
|
||||
3. If framework: implement here, bump the version, update the changelog
|
||||
with upgrade steps.
|
||||
4. The deployment then pins to the new version and applies any required
|
||||
config changes.
|
||||
|
||||
The framework does not name specific deployments, but it does aim to
|
||||
make each deployment's upgrade path obvious and mechanical.
|
||||
|
||||
## Code layout
|
||||
|
||||
See `docs/DEV.md` for the slicing plan and build history. See
|
||||
`SPEC.md` for the binding contract — section numbers (`§n.n`) in the
|
||||
codebase refer to that file.
|
||||
Reference in New Issue
Block a user