Ben Stull
29c96ea300
- 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.
81 lines
3.3 KiB
Markdown
81 lines
3.3 KiB
Markdown
# 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.
|