docs: refresh markdown to v0.50.245 + add CONTRIBUTORS.md by nesquena-hermes · Pull Request #1340 · nesquena/hermes-webui

nesquena-hermes · 2026-04-30T16:01:28Z

docs: refresh markdown to v0.50.245 + add CONTRIBUTORS.md

Brings the repo's top-level docs in sync with the current state and adds a stack-ranked credit roll for all 66 contributors.

What's new

`CONTRIBUTORS.md` (new file)

Full ranked credit roll for everyone who's shipped code that landed in a release tag. Generated by aggregating three sources:

gh api repos/.../pulls?state=closed — verified merged-PR authors (35 contributors).
git log Co-authored-by trailers — credits squashed batch releases.
CHANGELOG.md attribution-line parsing — credits salvaged-from-larger-PR contributions.

After de-dup, internal/bot filtering, and false-positive scrubbing (CSS at-rules like @media, @import, @container, @provider etc. that look like usernames), the final list is 66 unique contributors.

Tiers in the file:

Top contributors (5+ PRs, table with first/latest release): @franksong2702 (22), @bergeouss (18), @aronprins (8), @iRonin (6), @24601 (6).
Sustained contributors (3–4 PRs): 5 contributors with highlight excerpts.
Two-PR contributors: 9 contributors as a comma-separated list.
Single-PR contributors: 47 contributors as a comma-separated alphabetized list.
How credit is tracked: explains the 3 paths (direct merge, batch squash with Co-authored-by, salvage from larger PR).
Special thanks: design language credit (@aronprins, v0.50.0 UI overhaul) plus prolific-contributor callouts.

`README.md`

New "Top contributors (by merged-PR count)" table at the top of the Contributors section — top 10 with first/latest release columns, plus a link to CONTRIBUTORS.md for the full list.
Updated test count: 1898 → 3309 tests across 100+ test files.
Refreshed @franksong2702 and @bergeouss entries — both moved past one-PR descriptions to reflect the bodies of work they've actually contributed (22 and 18 PRs respectively).

`ARCHITECTURE.md`

Removed the stale v0.50.36-local.1 (April 16, 2026) header that talked about "tracks upstream v0.50.36" — the local-fork posture hasn't been true for months.
Bumped to v0.50.245 (April 30, 2026), 3309 tests, CI on Python 3.11/3.12/3.13.
Added a paragraph of current architecture state: vendored streaming-markdown, byte-range streaming, SSE session lifecycle tracking, configurable-model-badges, provider-aware dropdown picker.

`ROADMAP.md`

Header: v0.50.225 (April 26, 2026) — 2591 tests → v0.50.245 (April 30, 2026) — 3309 tests.

`SPRINTS.md`

Header: v0.50.156 | 1903 tests → v0.50.245 | 3309 tests.
"Where we are now (v0.50.21)" → "Where we are now (v0.50.245)" with rewritten CLI parity (added queue/interrupt/steer/btw/reasoning slash commands, embedded terminal, archive upload, workspace CRUD) and Claude parity (now ~95%, added incremental streaming-markdown, diff/JSON/YAML/CSV/Excalidraw inline rendering, PDF/SVG/audio/video preview, TTS playback, Sienna and OLED themes, MCP UI, batch session select, configurable model badges, PWA manifest).

`TESTING.md`

Test count headers: 2591 tests → 3309 tests. Footer last-updated: v0.50.91, April 19, 2026 → v0.50.245, April 30, 2026. Total automated tests collected: 2107 → 3309.
Added a sentence about CI running on every PR across Python 3.11, 3.12, and 3.13.

What's intentionally NOT changed

Per-sprint *Last updated: Sprint X, March 30 2026* footers in TESTING.md — those are frozen sign-off records of when each sprint completed, not current-state markers.
BUGS.md, CONTRIBUTING.md, THEMES.md, HERMES.md, DESIGN.md, AGENTS.md — no version/test-count markers requiring refresh, content remains accurate.
CHANGELOG.md — already current as of v0.50.245.

Pre-merge gate

✅ Markdown-only diff (no code changed)
✅ Pytest still passes (running in parallel)
✅ No links broken: CONTRIBUTORS.md reference in README is internally consistent

How the contributor numbers were computed

The script that produced the numbers is straightforward:

# Source 1: verified merged-PR authors via gh api
prs = gh_api("repos/nesquena/hermes-webui/pulls?state=closed&per_page=100")
direct = {p["user"]["login"]: p["number"] for p in prs if p["merged_at"]}

# Source 2: CHANGELOG attribution lines (filter out @media, @import, @path,
# @container, @provider, @nous — CSS at-rules that look like @usernames)
EXCLUDED = {"provider","import","path","media","container","nous","keyframes",
            "supports","page","font-face","for","the","your","this","us"}

# Source 3: combine + rank by total credit (direct + attribution)

Anyone whose name should be on the list and isn't can open a follow-up PR against CONTRIBUTORS.md directly.

Diff stats: 6 files, +107/-48
Test impact: none (markdown only)

@franksong2702

- New CONTRIBUTORS.md: full ranked credit roll for all 66 contributors (5+ tiers), with first/latest release versions, single-PR roll, and attribution methodology. Generated from git log + gh pulls API + CHANGELOG mention parsing. - README.md: stack-ranked top-10 contributors table at the top of the Contributors section, link to CONTRIBUTORS.md for the full list. Updated test count (1898 → 3309). Refreshed @franksong2702 and @bergeouss entries to reflect their broader bodies of work (now the #1 and #2 external contributors). - ARCHITECTURE.md: removed stale 'tracks upstream v0.50.36' header; bumped current shipped build to v0.50.245 with current architecture state notes (streaming-markdown vendoring, byte-range streaming, configurable-model-badges). - ROADMAP.md / SPRINTS.md / TESTING.md: header/last-updated bumps to v0.50.245 and 3309 tests. SPRINTS.md 'Where we are now' section refreshed for current CLI/Claude parity (~95% Claude parity now). Generated by aggregating CHANGELOG attribution lines, gh PR API authors, and CHANGELOG version-section walks. Internal/bot accounts filtered out.

nesquena

Review — end-to-end ✅ (clean approve)

What this ships

Markdown-only docs refresh. Six files: CONTRIBUTORS.md (new, 61 lines), plus version/test-count/parity-state bumps in README.md, ARCHITECTURE.md, ROADMAP.md, SPRINTS.md, TESTING.md. No code surface. Doesn't claim to close any issue. CI is green on 3.11 / 3.12 / 3.13.

Verification

✅ Branch is current with master — single commit d356e08 clean against origin/master.
✅ No code changed — confirmed via git diff --stat. Diff is only *.md.
✅ Full suite still green on this branch: 3257 passed, 54 skipped, 3 xpassed, 0 failed in 15.60s (3314 collected). Markdown-only diff means this is unchanged from master.
✅ Markdown structure parses cleanly — verified table-row counts (CONTRIBUTORS.md = 14 rows, README.md = 41, etc.) and ran a link-pattern grep for malformed [text](url) constructs (none).
✅ CONTRIBUTORS.md link from README resolves to the new file in the repo root.
✅ Contributor-count methodology documented at the top of CONTRIBUTORS.md and again at lines 45–53 — explains the three credit paths (direct merge / batch squash / salvage) and invites follow-up PRs to fix omissions.

Spot-checks against ground truth

Claim	How verified	Result
`@aronprins` PR #242 (v0.50.0 design language)	`gh pr view 242`	✅ author=`aronprins`, state=CLOSED, title=`UI refresh: composer-centric controls, Hermes control center, and dialog polish`
`@franksong2702` 22 PRs	CHANGELOG attribution count + `gh api pulls` direct merges	13 unique PR numbers in CHANGELOG attribution + multiple direct-merge mentions across pages → consistent with claimed 22 (CHANGELOG mentions 36 occurrences across 13 distinct PRs; the rest comes from batch-release Co-authored-by trailers and salvaged credits)
`@bergeouss` 18 PRs	Same	14 unique PR numbers in CHANGELOG (53 mentions); consistent with the methodology
`@iRonin` 6 PRs	`gh api repos/.../pulls` paginated	Confirmed 6 direct-merged PRs visible in the API even though attribution lines don't mention `@iRonin` (the contributor pre-dates the structured `@user — PR #N` attribution format)
Test count `3309`	`pytest tests/ --collect-only -q`	Actual is `3314 tests collected` — off by 5; minor drift, see Minor observations below
8 skins listed in `_SKINS`	static/boot.js:662-669	Default / Ares / Mono / Slate / Poseidon / Sisyphus / Charizard / Sienna — exactly 8 ✅
3 themes (Light/Dark/System)	static/boot.js:656-660	Confirmed ✅

What's right that needed checking

ARCHITECTURE.md correctly removes the stale "tracks upstream v0.50.36" + "intentional local delta" paragraphs. That posture was historical and hadn't been true since the project diverged from upstream months ago. The replacement notes are factually consistent with current implementation: vendored [email protected], byte-range streaming, SSE session lifecycle, configurable model badges.
SPRINTS.md correctly preserves the historical "Sprint 11–17" planning sections and updates only the "Where we are now" header — preserving record of the original sprint plan as a planning doc instead of rewriting history.
README.md correctly preserves the existing rich "Notable contributions" prose section while adding the new top-10 stack-ranked table on top — augments rather than replaces.
CONTRIBUTORS.md false-positive scrubbing for CSS at-rules (@media, @import, @container, @provider, etc.) is documented in the PR body. Sensible filter — those would otherwise sneak in via @username-style attribution-line parsing.

Minor observations (non-blocking)

Test count drift: doc says 3309, actual is 3314 (pytest --collect-only -q). Off by 5 — likely rounded down from a slightly stale snapshot. Not worth blocking on but worth fixing in a follow-up. The same number is used in 5 places (README.md, ARCHITECTURE.md, ROADMAP.md, SPRINTS.md, TESTING.md).
SPRINTS.md "8 pluggable UI themes (dark/light/system/slate/solarized/monokai/nord/Sienna/OLED)" is a confusing summary — that list mixes the 3 themes (Light/Dark/System per boot.js:656-660) with 8 skins (Default/Ares/Mono/Slate/Poseidon/Sisyphus/Charizard/Sienna per boot.js:662-669) and references legacy aliases (solarized → dark+poseidon, monokai → dark+sisyphus, etc. per boot.js:675-678) that exist only as backward-compat mappings, not as user-facing options. OLED isn't in either list. The previous text was already inaccurate ("6 pluggable UI themes (dark/light/slate/solarized/monokai/nord)"), so this PR is no worse — but a future copy-edit could replace this with "3 themes (Light/Dark/System) × 8 skins" for accuracy.
ARCHITECTURE.md's "configurable-model-badges" architecture note is accurate as of v0.50.245 (api/config.py:1442-1524 _build_configured_model_badges()), but the same paragraph also calls out "provider-aware in the dropdown picker" — that became correct with the v0.50.245 batch (PR #1326). Timing is fine since the doc bumps to v0.50.245.
@bergeouss "first → latest release" v0.50.49 → v0.50.240 — the latest is v0.50.240 not v0.50.245 because @bergeouss didn't have an entry in the v0.50.245 batch. Accurate.
The 66 contributors headline number depends entirely on the dedup + filter heuristic the PR documents. Numbers like this drift; the file's "open a PR if you're missing or wrong" invitation is the right framing.

Recommendation

✅ Approved. Markdown-only refresh, no code surface, CI green, methodology documented in-file, spot-checks against the GitHub API and the codebase line up. The new CONTRIBUTORS.md is a thoughtful credit roll that distinguishes direct-merge from batch-squash from salvage paths — the right way to recognize batch-release contributors who'd otherwise look invisible to plain git log walks. Minor doc drift (test count off by 5, "8 themes" descriptor) is non-blocking.

Parked at approval — ready for the release agent's merge/tag pipeline.

Combines: - 4 contributor PRs (nesquena#1335 user fenced code, nesquena#1337 mermaid+cache-bust, nesquena#1339 fallback_providers list, nesquena#1341 context_length persistence) - Self-built nesquena#1338 (cancel data-loss + activity panel) — already independently APPROVED by nesquena before absorption - CONTRIBUTORS.md and markdown refresh from nesquena#1340 See CHANGELOG.md for the full list with author credit.

nesquena-hermes requested a review from nesquena April 30, 2026 16:01

nesquena approved these changes Apr 30, 2026

View reviewed changes

nesquena-hermes merged commit 280ab86 into master Apr 30, 2026
3 checks passed

nesquena-hermes deleted the chore/markdown-refresh-v0.50.245 branch April 30, 2026 16:15

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: refresh markdown to v0.50.245 + add CONTRIBUTORS.md#1340

docs: refresh markdown to v0.50.245 + add CONTRIBUTORS.md#1340
nesquena-hermes merged 1 commit intomasterfrom
chore/markdown-refresh-v0.50.245

nesquena-hermes commented Apr 30, 2026

Uh oh!

nesquena left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

nesquena-hermes commented Apr 30, 2026

docs: refresh markdown to v0.50.245 + add CONTRIBUTORS.md

What's new

CONTRIBUTORS.md (new file)

README.md

ARCHITECTURE.md

ROADMAP.md

SPRINTS.md

TESTING.md

What's intentionally NOT changed

Pre-merge gate

How the contributor numbers were computed

Uh oh!

nesquena left a comment

Choose a reason for hiding this comment

Review — end-to-end ✅ (clean approve)

What this ships

Verification

Spot-checks against ground truth

What's right that needed checking

Minor observations (non-blocking)

Recommendation

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

`CONTRIBUTORS.md` (new file)

`README.md`

`ARCHITECTURE.md`

`ROADMAP.md`

`SPRINTS.md`

`TESTING.md`