README: clone URL is SSH-only, and Entrypoints omits script/precommit and script/projectname #36

New Issue

clawbot · 2026-08-09T18:41:07+02:00

clawbot commented

2026-08-09 18:41:07 +02:00

Two README defects found reviewing PR #35. Both pre-existing rather than
introduced there, so they were not reworked into it.

1. Getting Started clones over SSH on a public repo

The clone line uses git@git.eeqj.de:sneak/lora.vegas.git. The Gitea API
reports this repo as private: false, so an anonymous newcomer copy-pasting
that command fails — it requires a configured SSH key with access.

REPO_POLICIES.md requires Getting Started to be a "copy-pasteable
install/usage code block". A block that only works for people who already have
push access does not meet that in the sense intended.

It matches origin in a maintainer's checkout, so it may have been deliberate.
If read-only public access is intended, use the HTTPS clone_url. If the
repo is meant to be effectively private in practice, say so in the README
instead of leaving a command that silently fails for everyone else.

2. Entrypoints omits two scripts

REPO_POLICIES.md: the README "must document the provided scripts in an
Entrypoints section".

script/precommit and script/projectname both exist, are part of the
canonical twelve-script set, and are not listed. Every other script is.

script/projectname in particular is non-obvious — it exists so that
script/docker can stay byte-identical across repos, which is worth one line
of explanation rather than leaving a reader to guess why a script exists whose
only job is to echo a string.

Definition of done

The clone command in Getting Started works for an anonymous user, or the
README states plainly that access is restricted. Verify by actually running
the clone into a temp directory without SSH credentials in play — do not
assume the URL form is sufficient.
script/precommit and script/projectname are documented in Entrypoints,
in the same style as the existing bullets.
Entrypoints lists every script in script/ — check the directory rather
than working from the current list.
make fmt run; make fmt-check passes; make check green.
TODO.md updated.

Also worth fixing while there

The Entrypoints text says the .prettierignore exclusions carry "the reason
for each"; node_modules/ and yarn.lock have no reason comment (2 of 4).
Either add reasons or soften the wording. The phrasing is copied verbatim
from script/fmt's header comment, so fix both or neither.
The newest TODO.md Completed Steps entry lacks a terminal period, unlike
its neighbours.

Out of scope

The ## License section (#10, blocked on an owner decision).
Any restructuring of the section set — #11 settled that and it passed review.

Two README defects found reviewing PR #35. Both pre-existing rather than introduced there, so they were not reworked into it. ## 1. Getting Started clones over SSH on a public repo The clone line uses `git@git.eeqj.de:sneak/lora.vegas.git`. The Gitea API reports this repo as `private: false`, so an anonymous newcomer copy-pasting that command fails — it requires a configured SSH key with access. `REPO_POLICIES.md` requires Getting Started to be a "copy-pasteable install/usage code block". A block that only works for people who already have push access does not meet that in the sense intended. It matches `origin` in a maintainer's checkout, so it may have been deliberate. **If read-only public access is intended, use the HTTPS `clone_url`.** If the repo is meant to be effectively private in practice, say so in the README instead of leaving a command that silently fails for everyone else. ## 2. Entrypoints omits two scripts `REPO_POLICIES.md`: the README "must document the provided scripts in an **Entrypoints** section". `script/precommit` and `script/projectname` both exist, are part of the canonical twelve-script set, and are not listed. Every other script is. `script/projectname` in particular is non-obvious — it exists so that `script/docker` can stay byte-identical across repos, which is worth one line of explanation rather than leaving a reader to guess why a script exists whose only job is to echo a string. ## Definition of done 1. The clone command in Getting Started works for an anonymous user, or the README states plainly that access is restricted. Verify by actually running the clone into a temp directory without SSH credentials in play — do not assume the URL form is sufficient. 2. `script/precommit` and `script/projectname` are documented in Entrypoints, in the same style as the existing bullets. 3. Entrypoints lists every script in `script/` — check the directory rather than working from the current list. 4. `make fmt` run; `make fmt-check` passes; `make check` green. 5. `TODO.md` updated. ## Also worth fixing while there - The Entrypoints text says the `.prettierignore` exclusions carry "the reason for each"; `node_modules/` and `yarn.lock` have no reason comment (2 of 4). Either add reasons or soften the wording. The phrasing is copied verbatim from `script/fmt`'s header comment, so fix both or neither. - The newest `TODO.md` Completed Steps entry lacks a terminal period, unlike its neighbours. ## Out of scope - The `## License` section (#10, blocked on an owner decision). - Any restructuring of the section set — #11 settled that and it passed review.

clawbot referenced this issue

2026-08-10 15:49:52 +02:00

next: accumulated work for the current cycle #41

clawbot referenced this issue

2026-08-10 15:55:20 +02:00

next: accumulated work for the current cycle #41

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: sneak/lora.vegas#36