Aller au contenu
login
arrow_backRetour aux issues
Hebbian-Robotics/hflow #69

Docs: three stale claims in ARCHITECTURE.md and FORMAT.md (benchmark report, worker container, check list)

ecoDébutant documentation good first issue help wanted

descriptionDescription

Three claims in ARCHITECTURE.md and FORMAT.md have drifted from reality. Each fix is a sentence. ## 1. The benchmark report is described as future work, but it shipped - `docs/ARCHITECTURE.md:95` says "our benchmark report will publish what we measure" and `docs/ARCHITECTURE.md:244` says "A benchmark report (tracked in issues) will publish what the simple version achieves". - `docs/FORMAT.md:29` says "measured defaults are a benchmark-report deliverable" and `docs/FORMAT.md:74` says "configurable defaults pending the benchmark report". - Reality: `docs/BENCHMARKS.md` exists and publishes exactly those results. Every other page already links it (`docs/README.md`, `docs/FAQ.md`, `README.md`, `docs/RUNTIME.md`); ARCHITECTURE.md and FORMAT.md are the only pages that never do. - Fix: switch the four sentences to present tense and link `./BENCHMARKS.md`. ## 2. There is no worker container - `docs/ARCHITECTURE.md:135` says the Compose bundle is "Airflow 3.x services + Postgres + a worker container". - Reality: the bundle uses LocalExecutor with no separate worker. See the service list in `src/hflow/runtime/_templates.py` (postgres, airflow-init, user-venv-init, apiserver, scheduler, dag-processor, triggerer; "No Redis, no Celery worker") and the correct table already in `docs/RUNTIME.md:54`. - Fix: replace "+ a worker container" with the actual arrangement, for example "no separate worker container: LocalExecutor runs tasks in the scheduler". ## 3. The built-in check list omits `action_rate` - `docs/ARCHITECTURE.md:179` enumerates the built-in checks and says "Two of the classic cuts are corpus-relative judgments...: `episode_duration` ... and `content_digest`". - Reality: `src/hflow/checks.py` ships seven public checks, and `action_rate` (`src/hflow/checks.py:338`) is exactly the same corpus-relative species; `docs/CATALOG.md` already queries `action_rate_hz` in its cohort-statistics example. - Fix: add `action_rate` to the sentence (three corpus-relative cuts, not two). ## Definition of done - All four benchmark-report sentences read as present tense and link `./BENCHMARKS.md`. - ARCHITECTURE.md no longer claims a worker container and matches RUNTIME.md. - The check list names `action_rate`. - Line numbers above are from current main; re-check them before editing. ## Validation ```bash lychee --no-progress --include-fragments \ --exclude '^https://github\.com/Hebbian-Robotics/hflow/(issues|security/advisories/new)$' \ --exclude-path references/mcap-spec.md \ --exclude-path references/foxglove-CompressedVideo.proto . ```
codeOuvre sur GitHub