yonlu/yellowjacket
1
1
Fork 0
Code Issues 55 Pull Requests 6 Actions Packages Projects Releases 12 Wiki Activity

Docs: rewrite the README as a friendly landing page and move the technical docs elsewhere #50

New Issue
Open
opened 2026-08-18 05:58:15 +00:00 by logan · 3 comments
logan commented 2026-08-18 05:58:15 +00:00
Collaborator
Copy Link
Copy Source

Report

The README needs a pass. It should be welcoming to users of the app, have a screenshot, and act as a landing page. The technical documentation should move somewhere else.

Direction

README (user-facing):

  • What YellowJacket is, in two sentences, and a screenshot (ideally two or three — library, album detail, now playing — captured from the seeded fixture library so they are reproducible).
  • Supported formats (MP3, FLAC, OGG Vorbis, WAV), platforms (Linux desktop, Android APK; macOS via Homebrew from source; Windows deliberately unpublished), and how to install each.
  • Where releases and the Android APK come from, and the Obtainium-friendly URL.
  • The version-restart note (0.0.1 after 1.x) already documented in packaging/homebrew/README.md and docs/android-release.md — link it rather than repeating.
  • A pointer to the docs and to contributing.

Move to docs/ (or CONTRIBUTING.md): build/dev commands, the harness tiers, architecture. AGENTS.md already carries the architecture in depth and should stay the deep reference; the split is "what a user needs" vs "what a contributor needs".

Blocked-ish on the logo issue for the header image.

**Report** The README needs a pass. It should be welcoming to *users* of the app, have a screenshot, and act as a landing page. The technical documentation should move somewhere else. **Direction** README (user-facing): - What YellowJacket is, in two sentences, and a screenshot (ideally two or three — library, album detail, now playing — captured from the seeded fixture library so they are reproducible). - Supported formats (MP3, FLAC, OGG Vorbis, WAV), platforms (Linux desktop, Android APK; macOS via Homebrew from source; Windows deliberately unpublished), and how to install each. - Where releases and the Android APK come from, and the Obtainium-friendly URL. - The version-restart note (`0.0.1` after `1.x`) already documented in `packaging/homebrew/README.md` and `docs/android-release.md` — link it rather than repeating. - A pointer to the docs and to contributing. Move to `docs/` (or `CONTRIBUTING.md`): build/dev commands, the harness tiers, architecture. `AGENTS.md` already carries the architecture in depth and should stay the deep reference; the split is "what a user needs" vs "what a contributor needs". Blocked-ish on the logo issue for the header image.
logan added the Area/PackagingKind/Documentation
Priority
Medium
3
 labels 2026-08-18 14:36:12 +00:00
logan added a new dependency 2026-08-18 14:37:40 +00:00
#22 Branding: YellowJacket needs a logo/icon used everywhere
logan self-assigned this 2026-08-24 11:41:11 +00:00
logan added the
Status
In Progress
 label 2026-08-24 11:41:11 +00:00
logan commented 2026-08-24 11:41:12 +00:00
Author
Collaborator
Copy Link
Copy Source

Picking this up on docs/50-readme-landing-page.

Approach, in the issue's own order:

  • README becomes the landing page. What the app is, screenshots
    captured from the seeded fixture library (make sandbox-seed NAME=default
    → make dev-headless SEED=default, so they are reproducible), the four
    formats, and one install section per platform that says what is actually
    published: Linux from the release page / the Arch package, Android from
    the APK and the Obtainium-friendly URL, macOS from the Homebrew tap
    (built from source on the user's own Mac), Windows deliberately
    unpublished. The current install table names a darwin-universal.app.zip
    and a windows-amd64.exe that nothing produces, and the header claims
    Windows support while never mentioning Android — so this is a correctness
    pass as much as a friendliness one.
  • The 0.0.1-after-1.x note is linked to
    packaging/homebrew/README.md and docs/android-release.md rather than
    repeated.
  • The technical half moves to CONTRIBUTING.md: prerequisites, the
    system libraries, make setup / make dev / make build-prod, the
    harness tiers and the issue-tracker workflow, with CLAUDE.md left as
    the deep reference it already is.

What I am not doing, and why: the logo/header mark is #22 and stays
there — screenshots of the running app do not need it. That dependency is
recorded on this issue, so Gitea will decline to auto-close #50 from a
commit footer while #22 is open; whoever merges should close it by hand if
they are happy that the header image is the only thing left.

Picking this up on `docs/50-readme-landing-page`. Approach, in the issue's own order: - **README becomes the landing page.** What the app is, screenshots captured from the seeded fixture library (`make sandbox-seed NAME=default` → `make dev-headless SEED=default`, so they are reproducible), the four formats, and one install section per platform that says what is actually published: Linux from the release page / the Arch package, Android from the APK and the Obtainium-friendly URL, macOS from the Homebrew tap (built from source on the user's own Mac), Windows deliberately unpublished. The current install table names a `darwin-universal.app.zip` and a `windows-amd64.exe` that nothing produces, and the header claims Windows support while never mentioning Android — so this is a correctness pass as much as a friendliness one. - The `0.0.1`-after-`1.x` note is **linked** to `packaging/homebrew/README.md` and `docs/android-release.md` rather than repeated. - **The technical half moves to `CONTRIBUTING.md`**: prerequisites, the system libraries, `make setup` / `make dev` / `make build-prod`, the harness tiers and the issue-tracker workflow, with `CLAUDE.md` left as the deep reference it already is. **What I am not doing**, and why: the logo/header mark is #22 and stays there — screenshots of the running app do not need it. That dependency is recorded on this issue, so Gitea will decline to auto-close #50 from a commit footer while #22 is open; whoever merges should close it by hand if they are happy that the header image is the only thing left.
logan commented 2026-08-26 07:59:33 +00:00
Author
Collaborator
Copy Link
Copy Source

PR: #221 — CI green
(run 17994, check and e2e both success, WebKit step included).

What happened to the earlier run. The claim above was made by a
scheduled run that wrote the branch and was then killed by an API rate
limit before it committed anything. Its output survived in the worktree
and was picked up here: rebased onto a main that had moved 20 commits,
read as a reviewer rather than as its author, corrected, and shipped. So
the claim was real and is now answered.

Two things the review changed, both wrong against the code rather
than against taste:

  • The smart-playlist sentence offered "when you added it" as a rule
    field. fieldMap in backend/smartplaylist/smartplaylist.go has no
    such field and never has — the nearest real one is
    days_since_played, so the README says "how long since you played
    it".
  • CONTRIBUTING.md described make css-check as one pass. The target
    runs two (check-css-literals.mjs and check-css-nesting.mjs); the
    first is what catches a backtick inside a css literal.

Everything this issue's Direction asked for is in the diff except the
header mark, which is #22 and stays there — screenshots of the running
app do not need one. The three screenshots are 1440x900, captured from
the seeded fixture library (make sandbox-seed NAME=default →
make dev-headless SEED=default) so anyone can retake them and they
contain nobody's real library; they were re-captured against current
main in this run and come back pixel-equivalent, and
cmd/gentestdata/spec.go has not moved.

One thing for whoever merges. This issue carries a real Gitea
dependency on #22, so Gitea will decline to auto-close it from the
Closes #50 footer while #22 is open. If you are happy that the logo
is the only thing outstanding, close #50 by hand after the merge —
otherwise the footer will look like it fired and will not have.

Filed, not fixed here: #220 — scripts/skill-check.sh scans .pi/
and CLAUDE.md but not README.md or CONTRIBUTING.md, which is now
where a contributor reads a make target from. All 21 targets
CONTRIBUTING.md names exist today and nothing would say so if one were
renamed.

Leaving Status/In Progress on, and not merging.

PR: https://git.ljones.me/yonlu/yellowjacket/pulls/221 — **CI green** (run 17994, `check` and `e2e` both success, WebKit step included). **What happened to the earlier run.** The claim above was made by a scheduled run that wrote the branch and was then killed by an API rate limit before it committed anything. Its output survived in the worktree and was picked up here: rebased onto a `main` that had moved 20 commits, read as a reviewer rather than as its author, corrected, and shipped. So the claim was real and is now answered. **Two things the review changed**, both wrong against the code rather than against taste: - The smart-playlist sentence offered *"when you added it"* as a rule field. `fieldMap` in `backend/smartplaylist/smartplaylist.go` has no such field and never has — the nearest real one is `days_since_played`, so the README says "how long since you played it". - `CONTRIBUTING.md` described `make css-check` as one pass. The target runs two (`check-css-literals.mjs` and `check-css-nesting.mjs`); the first is what catches a backtick inside a `css` literal. **Everything this issue's Direction asked for is in the diff except the header mark**, which is #22 and stays there — screenshots of the running app do not need one. The three screenshots are 1440x900, captured from the seeded fixture library (`make sandbox-seed NAME=default` → `make dev-headless SEED=default`) so anyone can retake them and they contain nobody's real library; they were re-captured against current `main` in this run and come back pixel-equivalent, and `cmd/gentestdata/spec.go` has not moved. **One thing for whoever merges.** This issue carries a real Gitea dependency on #22, so **Gitea will decline to auto-close it from the `Closes #50` footer** while #22 is open. If you are happy that the logo is the only thing outstanding, close #50 by hand after the merge — otherwise the footer will look like it fired and will not have. **Filed, not fixed here:** #220 — `scripts/skill-check.sh` scans `.pi/` and `CLAUDE.md` but not `README.md` or `CONTRIBUTING.md`, which is now where a contributor reads a `make` target from. All 21 targets `CONTRIBUTING.md` names exist today and nothing would say so if one were renamed. Leaving `Status/In Progress` on, and not merging.
logan commented 2026-08-26 16:04:03 +00:00
Author
Collaborator
Copy Link
Copy Source

PR #221 is merged (5e25e14), and everything in the Direction
except one item has landed.

  • README.md is the landing page: what the app is, three screenshots
    from the seeded fixture library, the four formats, and one install
    section per channel naming what is actually published — the old
    table promised a darwin-universal.app.zip and a
    windows-amd64.exe that nothing has ever produced, and never
    mentioned Android.
  • CONTRIBUTING.md is new and takes the technical half.
  • The 0.0.1-after-1.x note is linked to the two packaging
    documents rather than copied, as asked.

What is left is the header image, which is #22's subject and the
reason this issue records a dependency. So this stays open behind that
dependency rather than being closed by hand, and the label is
Status/Blocked rather than Status/In Progress: nobody is working
it, and what it is waiting for is a logo.

Filed on the way and not fixed here: #220 — scripts/skill-check.sh
scans .pi/ and CLAUDE.md but not README.md or CONTRIBUTING.md,
which is now where a contributor reads a make target from. All 21
named there are correct today and nothing would say so if one were
renamed.

**PR #221 is merged** (`5e25e14`), and everything in the Direction except one item has landed. - `README.md` is the landing page: what the app is, three screenshots from the seeded fixture library, the four formats, and one install section per channel naming what is *actually* published — the old table promised a `darwin-universal.app.zip` and a `windows-amd64.exe` that nothing has ever produced, and never mentioned Android. - `CONTRIBUTING.md` is new and takes the technical half. - The `0.0.1`-after-`1.x` note is linked to the two packaging documents rather than copied, as asked. **What is left is the header image**, which is #22's subject and the reason this issue records a dependency. So this stays open behind that dependency rather than being closed by hand, and the label is `Status/Blocked` rather than `Status/In Progress`: nobody is working it, and what it is waiting for is a logo. Filed on the way and not fixed here: **#220** — `scripts/skill-check.sh` scans `.pi/` and `CLAUDE.md` but not `README.md` or `CONTRIBUTING.md`, which is now where a contributor reads a `make` target from. All 21 named there are correct today and nothing would say so if one were renamed.
logan added
Status
Blocked
1
 and removed
Status
In Progress
 labels 2026-08-26 16:04:03 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Area/Design
Area/Downloads
Area/Explore
Area/Library-UI
Area/Metadata
Area/Packaging
Area/Player
Area/Queue
Area/Settings
Area/Shell-Nav
Compat/Breaking
Breaking change that won't be backward compatible
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
 Platform/Android
Platform/Desktop
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Medium
3
The priority is medium
Priority
Low
4
The priority is low
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status
In Progress
Somebody is actively working on this right now
No labels Area/Packaging Kind/Documentation
Priority
Medium
3
Status
Blocked
1
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
logan yonlu
No Assignees logan
1 Participants
Notifications
Due Date
No due date set.
Depends on
#22 Branding: YellowJacket needs a logo/icon used everywhere
yonlu/yellowjacket
Reference: yonlu/yellowjacket#50