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

Repo layout: non-canonical root files, a confusing scripts/ directory, and a stale reformatted CONVENTIONS.md #97

New Issue
Closed
opened 2026-08-09 07:04:00 +02:00 by clawbot · 2 comments
clawbot commented 2026-08-09 07:04:00 +02:00
Collaborator
Copy Link
Copy Source

From the audit against the canonical REPO_POLICIES.md, verified against main at 61f42e6.

1. Files in the root that policy places in subdirectories. The policy states:

> Avoid putting files in the repo root unless necessary. Root should contain only project-level config files (README.md, Makefile, Dockerfile, LICENSE, .gitignore, .editorconfig, REPO_POLICIES.md, and language-specific config). Everything else goes in a subdirectory.

with a canonical subdirectory list including configs/ for "configuration templates and examples" and docs/ for "documentation and markdown (README.md stays in root)".

In the root today: CONVENTIONS.md (31 KB, belongs in docs/) and config.example.yml (belongs in configs/).

2. A scripts/ directory alongside the canonical script/. scripts/manual-test.sh sits in a directory that is neither the Scripts to Rule Them All entrypoint dir (script/) nor the canonical bin/. Having both script/ and scripts/ is actively confusing — they differ by one character and mean different things.

3. CONVENTIONS.md is a stale, reformatted copy of a canonical document. The policy requires:

> Cross-project documentation (such as this file) must include last_modified: YYYY-MM-DD in the YAML front matter so it can be kept in sync with the authoritative source as policies evolve.

diff against the canonical GO_HTTP_SERVER_CONVENTIONS.md produces 367 lines of difference. pixa's copy has no YAML front matter at all (canonical has title: and last_modified: 2026-02-22), is reflowed to unwrapped long lines, and uses different list markers and demoted heading levels. Because it was reformatted, there is no way to tell which differences are genuinely stale content and which are cosmetic — which is precisely the problem the last_modified requirement exists to prevent.

The contrast is instructive: the repo's REPO_POLICIES.md is byte-identical to canonical (sha256 117dde7f148ed3cd693b333312f6345a0a0ee84fadbbe5cca559ca6fed4a1775). That is the standard to meet.

Not flagged: TODO.md in the root. It is README-referenced and established convention across sneak's repos.

Definition of done

  1. config.example.yml → configs/; update Dockerfile:71 (COPY config.example.yml /etc/pixa/config.yml) and the README.md:119 reference.
  2. scripts/manual-test.sh → bin/; remove the scripts/ directory; update any references.
  3. CONVENTIONS.md replaced with a byte-identical copy of the canonical GO_HTTP_SERVER_CONVENTIONS.md (front matter and last_modified intact) and moved to docs/ — or deleted outright if the reference to it in REPO_POLICIES.md is considered sufficient. Recommend deleting: a vendored copy is a second thing to keep in sync, and the canonical source is already referenced.
  4. docker build . green (the COPY path change is the one thing that can break the image) and make check green.
  5. Pure file moves plus reference updates — no content changes to anything that moves, so the diff should be reviewable at a glance.

Coordination

Touches README.md and Dockerfile, both of which the open PRs modify. Do after both #55 and #54 merge.

From the audit against the canonical `REPO_POLICIES.md`, verified against `main` at `61f42e6`. **1. Files in the root that policy places in subdirectories.** The policy states: > Avoid putting files in the repo root unless necessary. Root should contain only project-level config files (`README.md`, `Makefile`, `Dockerfile`, `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, and language-specific config). Everything else goes in a subdirectory. with a canonical subdirectory list including `configs/` for "configuration templates and examples" and `docs/` for "documentation and markdown (README.md stays in root)". In the root today: `CONVENTIONS.md` (31 KB, belongs in `docs/`) and `config.example.yml` (belongs in `configs/`). **2. A `scripts/` directory alongside the canonical `script/`.** `scripts/manual-test.sh` sits in a directory that is neither the Scripts to Rule Them All entrypoint dir (`script/`) nor the canonical `bin/`. Having both `script/` and `scripts/` is actively confusing — they differ by one character and mean different things. **3. `CONVENTIONS.md` is a stale, reformatted copy of a canonical document.** The policy requires: > Cross-project documentation (such as this file) must include `last_modified: YYYY-MM-DD` in the YAML front matter so it can be kept in sync with the authoritative source as policies evolve. `diff` against the canonical `GO_HTTP_SERVER_CONVENTIONS.md` produces **367 lines of difference**. pixa's copy has no YAML front matter at all (canonical has `title:` and `last_modified: 2026-02-22`), is reflowed to unwrapped long lines, and uses different list markers and demoted heading levels. Because it was reformatted, there is no way to tell which differences are genuinely stale content and which are cosmetic — which is precisely the problem the `last_modified` requirement exists to prevent. The contrast is instructive: the repo's `REPO_POLICIES.md` is byte-identical to canonical (sha256 `117dde7f148ed3cd693b333312f6345a0a0ee84fadbbe5cca559ca6fed4a1775`). That is the standard to meet. **Not flagged:** `TODO.md` in the root. It is README-referenced and established convention across sneak's repos. ## Definition of done 1. `config.example.yml` → `configs/`; update `Dockerfile:71` (`COPY config.example.yml /etc/pixa/config.yml`) and the `README.md:119` reference. 2. `scripts/manual-test.sh` → `bin/`; remove the `scripts/` directory; update any references. 3. `CONVENTIONS.md` replaced with a byte-identical copy of the canonical `GO_HTTP_SERVER_CONVENTIONS.md` (front matter and `last_modified` intact) and moved to `docs/` — **or** deleted outright if the reference to it in `REPO_POLICIES.md` is considered sufficient. Recommend deleting: a vendored copy is a second thing to keep in sync, and the canonical source is already referenced. 4. `docker build .` green (the `COPY` path change is the one thing that can break the image) and `make check` green. 5. Pure file moves plus reference updates — no content changes to anything that moves, so the diff should be reviewable at a glance. ## Coordination Touches `README.md` and `Dockerfile`, both of which the open PRs modify. Do **after** both #55 and #54 merge.
clawbot added this to the 1.0.0 milestone 2026-08-09 07:04:00 +02:00
clawbot commented 2026-10-04 19:43:17 +02:00
Author
Collaborator
Copy Link
Copy Source

Plan, checked against next at 847ad5b. All three items are still there; configs/ already exists (it holds configs/Caddyfile), and the Dockerfile no longer copies config.example.yml.

  • config.example.yml moves to configs/config.example.yml, unchanged; the references to it in README.md (the Getting Started copy command and the "all options" line) and the comments in internal/config/config.go follow.
  • scripts/manual-test.sh is deleted with its scripts/ directory, not moved: the login, URL generation, encrypted URL and error checks it ran by hand are now Go tests in internal/handlers (#76, #77). The PR lists anything it checked that no test covers; if there is something that needs a running server, say so on this issue instead of deleting.
  • CONVENTIONS.md is deleted: REPO_POLICIES.md already links the canonical GO_HTTP_SERVER_CONVENTIONS.md, and a reformatted copy is a second thing to keep in sync. Any reference to it follows.
  • Moves and deletions plus reference updates only; nothing that moves changes content.

Out of scope: REPO_POLICIES.md no longer matches the canonical copy in sneak/prompts; that is its own unit.

Model: opus-5-5

Plan, checked against `next` at `847ad5b`. All three items are still there; `configs/` already exists (it holds `configs/Caddyfile`), and the `Dockerfile` no longer copies `config.example.yml`. - `config.example.yml` moves to `configs/config.example.yml`, unchanged; the references to it in `README.md` (the Getting Started copy command and the "all options" line) and the comments in `internal/config/config.go` follow. - `scripts/manual-test.sh` is deleted with its `scripts/` directory, not moved: the login, URL generation, encrypted URL and error checks it ran by hand are now Go tests in `internal/handlers` (https://git.eeqj.de/sneak/pixa/issues/76, https://git.eeqj.de/sneak/pixa/issues/77). The PR lists anything it checked that no test covers; if there is something that needs a running server, say so on this issue instead of deleting. - `CONVENTIONS.md` is deleted: `REPO_POLICIES.md` already links the canonical `GO_HTTP_SERVER_CONVENTIONS.md`, and a reformatted copy is a second thing to keep in sync. Any reference to it follows. - Moves and deletions plus reference updates only; nothing that moves changes content. Out of scope: `REPO_POLICIES.md` no longer matches the canonical copy in `sneak/prompts`; that is its own unit. Model: opus-5-5
clawbot commented 2026-10-04 19:51:27 +02:00
Author
Collaborator
Copy Link
Copy Source

Implemented as planned in #194. One addition: the startup error for the placeholder signing key also names the new path.

Model: opus-5-5

Implemented as planned in https://git.eeqj.de/sneak/pixa/pulls/194. One addition: the startup error for the placeholder signing key also names the new path. Model: opus-5-5
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
critical
Extremely important: data loss, a security hole, production down, or basic use impossible
 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#97