sneak/pixa
1
0
Fork 0
Code Issues 51 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

README describes storage paths, formats, and features that do not match the code #74

New Issue
Open
opened 2026-08-09 03:47:33 +02:00 by clawbot · 0 comments
clawbot commented 2026-08-09 03:47:33 +02:00
Collaborator
Copy Link
Copy Source

Verified against main at 61f42e6. Docs-only issue; each item is a factual mismatch between README.md and the implementation.

  1. On-disk layout is wrong. README.md:38-45 documents <statedir>/cache/src-content/, cache/src-metadata/, and cache/dst-content/. The actual directories (internal/imgcache/cache.go:52-65) are cache/sources, cache/variants, cache/metadata. The SQL schema comments repeat the README's wrong paths (internal/database/schema/001_initial_schema.sql, lines 5, 12, 38). Fix the docs (renaming the directories would be a migration for no benefit).

  2. The format list contradicts itself. README.md:59 says <format> is one of orig, png, jpeg, webp. README.md:88, in the signature spec, lists jpeg, png, webp, avif, gif, orig. The code (internal/imgcache/urlparser.go:241-258) accepts jpg, avif, gif, and original as well. Make one accurate list.

  3. allow_http is undocumented and contradicts a stated guarantee. README.md:57 states "Images are only fetched from origins using TLS with valid certificates." config.example.yml:26 documents allow_http, and internal/httpfetcher/httpfetcher.go:300-303 honors it. The README should describe the guarantee as conditional and document the key.

  4. Two Architecture claims overstate what exists.

    • README.md:49 — "In-process caching of request-to-output mappings targets 1-5k r/s". The field backing this is dead (filed separately). Either that issue implements it or this line must go.
    • README.md:128 — "Metrics: Prometheus" implies pixa-specific metrics. Only generic HTTP metrics exist, and only when metrics credentials are configured (filed separately).

Definition of done

  1. Items 1-3 corrected in README.md; item 1 also corrected in the 001_initial_schema.sql comments.
  2. Items 4a/4b either corrected or explicitly deferred with a link to the issue that will make them true — no claim left standing that the code does not support.
  3. make fmt run so the markdown matches repo formatting (prettier, 4-space tabs, proseWrap: always); formatted output committed.
  4. make check green.

Process note

Docs-only (plus SQL comments). Per repo policy this skips adversarial review and goes straight to merge-ready once make check is green — provided the change really touches nothing but comments and markdown.

Verified against `main` at `61f42e6`. Docs-only issue; each item is a factual mismatch between `README.md` and the implementation. 1. **On-disk layout is wrong.** `README.md:38-45` documents `<statedir>/cache/src-content/`, `cache/src-metadata/`, and `cache/dst-content/`. The actual directories (`internal/imgcache/cache.go:52-65`) are `cache/sources`, `cache/variants`, `cache/metadata`. The SQL schema comments repeat the README's wrong paths (`internal/database/schema/001_initial_schema.sql`, lines 5, 12, 38). Fix the docs (renaming the directories would be a migration for no benefit). 2. **The format list contradicts itself.** `README.md:59` says `<format>` is one of `orig`, `png`, `jpeg`, `webp`. `README.md:88`, in the signature spec, lists `jpeg, png, webp, avif, gif, orig`. The code (`internal/imgcache/urlparser.go:241-258`) accepts `jpg`, `avif`, `gif`, and `original` as well. Make one accurate list. 3. **`allow_http` is undocumented and contradicts a stated guarantee.** `README.md:57` states "Images are only fetched from origins using TLS with valid certificates." `config.example.yml:26` documents `allow_http`, and `internal/httpfetcher/httpfetcher.go:300-303` honors it. The README should describe the guarantee as conditional and document the key. 4. **Two Architecture claims overstate what exists.** - `README.md:49` — "In-process caching of request-to-output mappings targets 1-5k r/s". The field backing this is dead (filed separately). Either that issue implements it or this line must go. - `README.md:128` — "**Metrics**: Prometheus" implies pixa-specific metrics. Only generic HTTP metrics exist, and only when metrics credentials are configured (filed separately). ## Definition of done 1. Items 1-3 corrected in `README.md`; item 1 also corrected in the `001_initial_schema.sql` comments. 2. Items 4a/4b either corrected or explicitly deferred with a link to the issue that will make them true — no claim left standing that the code does not support. 3. `make fmt` run so the markdown matches repo formatting (prettier, 4-space tabs, `proseWrap: always`); formatted output committed. 4. `make check` green. ## Process note Docs-only (plus SQL comments). Per repo policy this skips adversarial review and goes straight to `merge-ready` once `make check` is green — provided the change really touches nothing but comments and markdown.
clawbot added this to the 1.0.0 milestone 2026-08-09 03:47:33 +02:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
merge-ready
needs-checks
needs-rebase
needs-review
needs-rework
No labels
Milestone
No items
No Milestone 1.0.0
Projects
Clear projects
No projects
Assignees
Clear assignees
clawbot sneak (Jeffrey Paul)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sneak/pixa#74