Skip to content

Monolithic index.html and api-reference.md make every v5 PR conflict with every other #15299

Closed

Description

@clubanderson

Problem

Nearly every PR to v5 conflicts with every other PR to v5, because two monolithic files are touched by almost all of them:

  • src/pkg/dashboard/static/index.html — ~60 400 lines: the whole inline style sheet, several hundred JS function groups and every body template in one file. Embedded via //go:embed static, gzipped once at startup, CSP-hashed; many tests assert on its literal HTML/ids/classes and a node harness loads functions from it.
  • src/docs/api-reference.md — one large route table regenerated by src/scripts/check-api-reference-citations.sh --fix whenever server.go / api.go routes change.

Any two PRs that touch the dashboard (or any route) collide in these files even when their changes are unrelated. After each merge, every open PR has to be rebased, regenerated and re-pushed before Tide will look at it again, and the rebase itself is error-prone (hand-merging unrelated hunks in a 60k-line file).

Evidence (today)

Each of these merges re-conflicted the open dashboard PRs, forcing a rebase round across the queue:

#15216, #15251, #15122, #15240, #15267, #15256, #15278, #15279, #15281 — and since then #15285, #15186 and #15290 did the same (#15186: +315/-? in index.html; #15290: a CSS-only change that still collided).

Proposal

Decompose both files so a PR touches only the area it changes, without changing served bytes or breaking CSP/tests:

Part 1 — dashboard: split index.html into per-area sources under src/pkg/dashboard/static-src/ (head.html, css/<area>.css, js/<area>.js, html/<area>.html, glue files, manifest.txt) and a go:generate concatenator that writes the committed static/index.html. The artifact stays committed and is byte-identical, so the embed, CSP hashes, node harnesses and all existing tests are unchanged. TestIndexHTMLIsGenerated fails when artifact and sources drift; make dashboard-gen regenerates. Conflicts in index.html are resolved by taking the base's copy and regenerating — never by hand (documented in src/docs/dashboard-source-layout.md).

Part 2 — api-reference: split src/docs/api-reference.md into src/docs/api-reference/<area>.md grouped by route prefix / handler file, with api-reference.md becoming an index that keeps existing anchors; check-api-reference-citations.sh walks the directory and --fix writes only the affected area's file.

Activity

  1. hivecommons-hive commented on Oct 29, 2026

    @hivecommons-hive
    Contributor

    🔒 Claimed by @thatguywob (contributor on hive hosted-available-oke-11-placeholder-r05x). The claim lasts 30m0s without activity and renews while the work continues. Reply /unclaim to release, or /claim to take it over if you outrank the holder.

  2. added
    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.
    on Oct 29, 2026
  3. hivecommons-hive commented on Oct 29, 2026

    @hivecommons-hive
    Contributor

    🔓 Claim by @thatguywob released (lease revoked).

  4. added 6 commits that reference this issue on Oct 29, 2026
    35d3162
    78fc440
    dcbf68a
    bf24de3
    fcc6802
    cfaf252
  5. added a commit that references this issue on Oct 30, 2026
    35b47e2
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions