Skip to content

Epic: gosqlx.dev + README visual, performance & discoverability overhaul (audit 2026-10-14) #634

Open
Open
Epic: gosqlx.dev + README visual, performance & discoverability overhaul (audit 2026-10-14)#634
Labels
enhancementNew feature or requesthigh-priority

Description

@ajitpratap0
ajitpratap0
opened on Oct 14, 2026

Executive summary

  • Pages go blank after load (P0). FadeIn.tsx swaps visible server HTML for an opacity:0 motion tree after hydration; hero, /compare, /blog and scroll sections stay faint for seconds (500px hero showed only the version badge after 4s). Fixing it is the biggest win for LCP, perceived quality and crawler rendering.
  • Three SEO bugs need fixing now. Layout-level canonical: '/' leaks to /docs/, /playground/, /privacy/ and 404; sitemap omits /compare and lists redirecting non-slash URLs; most pages have no og:image.
  • Some claims are wrong or unsourced (credibility risk before the HN launch, P0: Submit dev.to article to Hacker News + r/golang — top-of-funnel launch #442). Star count hardcoded "1.2k" (real: 120; CSP blocks the fetch), competitor numbers contradict across pages, Complex Multi-JOIN chart 574K vs table 376K, headline throughput 1.38M/1.40M/1.5M+ (the only 1.38M test is tokenizer-only).
  • README headline snippet depended on an unreleased API. Resolved by tagging v1.15.0 at 31b5b1c; README also has ~14 badges (two retired), an overflowing install table, an empty adopters section and no demo media.
  • Visually generic. Monochrome hero, 32px raster logo, three font families, text-initial dialect cards, raw-JSON demo, light mode via ~300 lines of overrides.
  • More client code than static content needs. Sentry Replay/logs on every page, WASM instantiated on every home visit, static pages marked 'use client'.
  • No content engine. /blog is release notes only; no comparison pages, no served llms.txt, no RSS, no awesome-list presence.
  • Order of work: ~6 hotfix PRs, then Phase 1 (correctness, SEO plumbing, motion/perf), Phase 2 (visual), Phase 3 (README and GitHub), Phase 4 (content/distribution), Phase 5 (measure). One generated metrics file checked in CI keeps every number consistent.

Scorecard (audit 2026-10-14)

Area Grade Why
Visual C Coherent dark look but monochrome hero, weak mark, three font families, text-initial dialect cards, raw-JSON demo; light mode via overrides
Performance D Content hidden until hydration, WASM on every home visit, Sentry Replay in every bundle; probe FCP 6.2s (not yet confirmed in Lighthouse)
SEO D Canonicals to home on key pages, missing og:image, sitemap gaps, doubled brand in titles, short docs descriptions
Docs UX C Extensive content, but literal backticks, changelog-first quickstart, truncated TOC, title-only search, no edit/last-updated
Product pages D Contradictory unsourced competitor numbers, chart/table mismatch, CGo green check, concatenated AST leaves, VS Code says 10 rules vs 30
README/GitHub D Headline snippet did not compile on the released tag, retired badges, overflow table, empty adopters, no demo/social preview, root clutter
Accessibility C Skip link/ARIA present; muted text fails AA, no :focus-visible, search modal focus, partial reduced-motion, no playground SSR h1
Discoverability D No served llms.txt/RSS, /blog is a changelog, no comparison pages, no awesome-list listings, 120 stars

99 verified findings: 9 P0, 39 P1, 38 P2, 13 P3.

Decisions and open questions

  1. v1.15.0: DECIDED. Tag v1.15.0 back-dated at commit 31b5b1c (2026-07-30), which contains ParseTree. Revert-README option dropped; Phase 3.6 no longer waits on tagging.
  2. Headline throughput: the only 1.38M comparison is a tokenizer-only sustained test. Change the headline to the measured stage-labelled figure (e.g. ~712 ns/op parse from tokens) before the HN launch? Recommended yes.
  3. Competitor numbers: remove now (recommended) or label as "unverified estimate" until the 4.1 harness exists? Which versions/corpora are fair?
  4. Sentry: is Session Replay or logs used? Check sendDefaultPii: true against /privacy copy.
  5. WASM caching: is deferral alone enough, or schedule a content-hashed immutable WASM (touches scripts/build-wasm.sh, wasm_exec.js)?
  6. Brand: keep mascot as primary mark or adopt a flat SVG monogram? Who produces logo, demo GIF and social preview?
  7. Third-party marks: trademark terms for Anthropic/Cursor/VS Code/database logos; are text plus neutral glyphs acceptable?
  8. /blog to /changelog rename: OK to change indexed URLs (permanent redirects)? Who writes the 6 evergreen posts?
  9. Docs IA restructure (4.6): before or after the launch (moves URLs, needs redirects)?
  10. Repo admin actions: social preview, About text, topics, homepage need UI/admin; PAT-based step or manual?
  11. Tracked .claude/settings.json: intentional? (render.yaml and glama.json must stay at root.)
  12. Unsourced claims: sources for dialect % values (95/85/80) in DialectShowcase.tsx, "20,000+ concurrent ops", "800+ tests"; unsourced claims get dropped.
  13. Review bandwidth: ~35 small PRs against a code-owner-review ruleset with one maintainer; batch Phase 1 into 3-4 merge windows. No --admin merges.
  14. Search Console and Bing: are properties verified? A baseline is required before Phase 4 targets.
  15. Launch timing (P0: Submit dev.to article to Hacker News + r/golang — top-of-funnel launch #442): hold Show HN until HF-1..5, Phase 1, Phase 3 and 4.1/4.2 are done?

Tasks

Tasks

Hotfixes

Phase 1 – Foundations

Phase 2 – Visual redesign

Phase 3 – README & GitHub

Phase 4 – Content & discoverability

Phase 5 – Measure & iterate

Refs

Activity

  1. ajitpratap0
    added
    enhancementNew feature or request
    high-priority
    on Oct 14, 2026

  2. ajitpratap0 commented on Oct 14, 2026

    @ajitpratap0
    ajitpratap0
    on Oct 14, 2026
    OwnerAuthor

    Automated run: W0 quality gates

    Issue PR Status Note
    #635 #687 merged Squash-merged 2026-10-14T14:20:36Z; up to date with main, no rebase needed. Checks green or skipped before merge, incl. "Typecheck, lint and build" and Vercel. Lighthouse was pending at first look, then cleared. "Green on main" for website-ci.yml confirms on the push-to-main run. Visual check not done: Vercel preview redirected to login and was not authenticated, so 1440/500px and dark/light were not viewed. Change is tooling only (no site source), so visual regression risk judged low.

  3. ajitpratap0 commented on Oct 14, 2026

    @ajitpratap0
    ajitpratap0
    on Oct 14, 2026
    OwnerAuthor

    Automated run: W1 hotfixes

    Issue PR Status Note
    #636 #688 merged Squash-merged 2026-10-14T14:45:31Z; one Lighthouse run hit a Google Fonts network flake and was rerun once. Visual check not done (Vercel SSO login).
    #637 #691 merged Rebased onto main (new head b6fd465); website typecheck, lint (0 errors, 8 warnings) and build pass. Local next start checked at ~406px: no horizontal scroll, no console errors. Non-blocking review items left open.
    #638 #689 merged Conflicts in page.tsx and Hero.tsx resolved in favour of main, PR stars prop kept; one proxy.golang.org flake in Race Detector rerun green. Visual check not done (Vercel SSO login).
    #639 #692 merged Conflict in TrustSection.tsx resolved (formatStars kept); gates green; checked /benchmarks/ locally in narrow width only.
    #640 #690 merged Rebased with no conflicts; one proxy.golang.org flake rerun green. Not a website PR. GitHub About text still says "1.5M+ ops/sec" and needs gh repo edit --description.

  4. ajitpratap0 commented on Oct 14, 2026

    @ajitpratap0
    ajitpratap0
    on Oct 14, 2026
    OwnerAuthor

    Automated run: W2 phase-1a

    Issue PR Status Note
    #641 #699 merged Head metadata only; squash-merged 2026-10-14T15:54:50Z, all CI green. Four non-blocking review suggestions not applied.
    #652 #693 merged Follow-up commit 2652502: light-mode inline code contrast, all-level heading slugs, TOC clamp, dead code override removed.
    #653 #694 merged Merged main into branch, then squash-merged; one flaky ubuntu test job rerun and passed. Rendered pages not visually checked (Vercel preview behind login).
    #657 #696 merged Rebased onto main (one conflict in benchmarks/page.tsx), docs fixes added; squash-merged after green CI. Rendered pages not visually checked (Vercel preview behind login).

  5. ajitpratap0 commented on Oct 14, 2026

    @ajitpratap0
    ajitpratap0
    on Oct 14, 2026
    OwnerAuthor

    Automated run: W3 phase-1b

    Issue PR Status Note
    #642 #705 merged Squash-merged, no rebase needed, all checks green. Visual check not done (Vercel preview behind login). Description-tag grep returned nothing, unresolved.
    #643 #702 merged Rebased over blog.ts conflict, kept main's deriveDescription plus updated. Squash-merged, all checks green. Follow-ups: docs dateModified uses file mtime, breadcrumb hardcodes /blog/, aggregateRating risk. Rich Results not run.
    #644 #703 merged Rebased onto main, no conflicts. Squash-merged, 30 checks green. Feature branch had a force-push. Social unfurl debuggers not checked on production.
    #646 #700 merged Rebased over blog page conflict, kept JsonLd and <div>. Squash-merged, checks green. Verified one main and one h1 on a local production build, not in a browser.
    #647 #704 merged Rebased over layout conflict, kept main's Providers. Squash-merged, 30 checks green. PR body is stale. Visual check was partial: /benchmarks and /compare on local next start, no 1440 or dark-mode check.
    #649 #701 merged Rebased (layout/playground), moved ServiceWorkerRegister to playground page. Squash-merged, checks green. Preview behind login, so no browser check on the rebased build.
    #650 #706 merged Rebased, took main's Providers/LazyMotion, removed ScrollProgressBar, kept lazy SearchModal. Squash-merged, checks green. Narrow-width and Cmd+K checked on local build. No 1440 or light-mode check.

    Checkboxes: all seven rows were already ticked in the epic body, so the body was not edited.

  6. ajitpratap0 commented on Oct 14, 2026

    @ajitpratap0
    ajitpratap0
    on Oct 14, 2026
    OwnerAuthor

    Automated run: W4 phase-1c

    Issue PR Status Note
    #645 #708 merged Squash-merged, CLEAN, no --admin. Follow-ups still need tracking: unlabelled throughput/competitor claims in llms-full.txt (#679/#684), root llms.txt drift check (#658/#684), robots.txt Host line, feed move to /changelog/feed.xml after #676, H1 strip in llms-full.txt. Vercel preview needed login, so visual checks were skipped; feed and robots.txt checked via fetch.
    #655 #707 merged Squash-merged after merging main into branch (typecheck, lint, build pass). Minor review items not changed; axe on 8 routes not run. Visual checks skipped (Vercel preview login).
    #656 #709 open Rebased and conflicts resolved; all checks pass except Vercel (rate limited, retry in 24h). Not merged. Needs Vercel re-run, Chrome check, then squash merge.
    #658 #710 open Rebased onto main (head c4eb175), README metrics check and vet clean. All checks pass except Vercel (rate limited). Not merged; merge once Vercel re-runs green, no --admin.

  7. ajitpratap0 commented on Oct 14, 2026

    @ajitpratap0
    ajitpratap0
    on Oct 14, 2026
    OwnerAuthor

    Automated run: W5 tokens + repo hygiene

    Epic checkboxes: #659 and #671 were already ticked in the body, so the body was not edited. #664 and #670 stay unticked until merged.

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

    enhancementNew feature or requesthigh-priority

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions