mirror of
https://github.com/nesquena/hermes-webui.git
synced 2026-05-30 21:50:16 +00:00
docs(rfcs): establish docs/rfcs/ convention and polish turn-journal RFC
Moves docs/turn-journal-rfc.md → docs/rfcs/turn-journal.md, establishing the convention for future design documents on hermes-webui's data-at-rest and recovery surfaces. Adds docs/rfcs/README.md describing when an RFC applies (large changes, durability/recovery semantics, new infrastructure primitives) and the simple status header convention. Polish on turn-journal.md: - Added 3-line status header (Status / Author / Created) at top. - Light tone edits on two flourishes that read fine in a PR description but felt off in permanent repo documentation. Author's voice preserved throughout the rest of the document. Co-authored-by: ai-ag2026 <261867348+ai-ag2026@users.noreply.github.com>
This commit is contained in:
@@ -40,6 +40,8 @@ Thumbs.db
|
||||
docs/*
|
||||
!docs/ui-ux/
|
||||
!docs/ui-ux/**
|
||||
!docs/rfcs/
|
||||
!docs/rfcs/**
|
||||
!docs/docker.md
|
||||
!docs/supervisor.md
|
||||
!docs/troubleshooting.md
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
# RFCs
|
||||
|
||||
This directory holds design documents for hermes-webui features that are
|
||||
worth thinking through in writing before (or alongside) implementation —
|
||||
typically when the change touches durability, recovery, schema, or cross-
|
||||
cutting infrastructure.
|
||||
|
||||
## Conventions
|
||||
|
||||
- One file per RFC. Filename is the topic (kebab-case), not a number.
|
||||
- Top of every RFC carries a small header:
|
||||
|
||||
- **Status:** Proposed | Accepted | Implemented | Withdrawn
|
||||
- **Author:** @github-handle
|
||||
- **Created:** YYYY-MM-DD
|
||||
|
||||
- Sections usually include: Problem, Goals, Non-goals, Proposal, Open
|
||||
questions, Rollout plan. Skip what doesn't apply.
|
||||
- An RFC is a starting point for review. Comments and revisions land via PR
|
||||
edits, not separate discussion threads.
|
||||
|
||||
## When to file an RFC
|
||||
|
||||
- The change is large enough that you want consensus before writing code.
|
||||
- The change touches data-at-rest formats or recovery semantics.
|
||||
- The change introduces a new architectural primitive (journal, queue,
|
||||
scheduler, cache layer) that other features will build on.
|
||||
- A reviewer asks for one during code review.
|
||||
|
||||
When in doubt, just ship the code — small features don't need RFCs.
|
||||
|
||||
## Current RFCs
|
||||
|
||||
- [`turn-journal.md`](turn-journal.md) — Crash-safe WebUI turn journal for
|
||||
recovering interrupted chat submissions.
|
||||
@@ -1,5 +1,9 @@
|
||||
# RFC: WebUI Turn Journal for Crash-Safe Chat Submissions
|
||||
|
||||
- **Status:** Proposed
|
||||
- **Author:** @ai-ag2026
|
||||
- **Created:** 2026-05-11
|
||||
|
||||
## Problem
|
||||
|
||||
A WebUI chat turn crosses several durability boundaries:
|
||||
@@ -19,7 +23,7 @@ The missing primitive is a small write-ahead journal for turns: record the submi
|
||||
- Preserve the exact user-submitted turn, including attachments metadata, before any provider or worker work starts.
|
||||
- Make crash recovery deterministic: a submitted-but-unfinished turn can be reported or reconstructed without guessing.
|
||||
- Keep the journal append/update format simple enough for startup recovery, CLI audit, and future API repair endpoints.
|
||||
- Avoid turning recovery into a background daemon. This is storage hygiene, not a tiny cult with a scheduler.
|
||||
- Avoid turning recovery into a background daemon. This is storage hygiene, not a long-running service.
|
||||
|
||||
## Non-goals
|
||||
|
||||
@@ -151,4 +155,4 @@ The first implementation PR should be deliberately small:
|
||||
- one call site: append `submitted` before worker start
|
||||
- audit-only report of pending journal turns
|
||||
|
||||
Do **not** combine the first implementation with replay/repair. Replay is where footguns rent office space.
|
||||
Do **not** combine the first implementation with replay/repair. Replay is where most of the bugs in WAL systems live; ship the writer and audit first, prove the format, then add repair.
|
||||
Reference in New Issue
Block a user