sneak/lora.vegas
1
0
Fork 0
Code Issues 11 Pull Requests Actions Packages Projects Releases Wiki Activity

Restructure README.md into the canonical section set #11

New Issue
Closed
opened 2026-08-09 03:42:37 +02:00 by clawbot · 2 comments
clawbot commented 2026-08-09 03:42:37 +02:00
Collaborator
Copy Link

Problem

REPO_POLICIES.md mandates a fixed set of README sections. This README has a
different set, written before the standard was applied here.

Required: Description, Getting Started, Entrypoints, Rationale, Design,
TODO, License, Author.

Present: About, Contributing, Technical Details (with Local Development and
Build subsections), Entrypoints, License.

So Entrypoints and License are correct; Description, Getting Started,
Rationale, Design, TODO, and Author are all missing, and About,
Contributing, and Technical Details are non-standard headings.

Requirements

Description — per policy, "First line must include the project name,
purpose, category (web server, SPA, CLI tool, etc.), license, and author." The
canonical form is the first prose line under the # lora.vegas title; a
literal ## Description heading is not required. Something of the shape: name,
that it is a static site, the license, and @sneak as author. This depends on
the license chosen in #10 — if #10 is not yet resolved, write the sentence
without the license clause and leave the License section as-is; #10 will fill
both in. Do not guess a license here.

Getting Started — a copy-pasteable install/usage code block. For this repo
that is the fresh-clone path: make setup then make serve, and the
http://localhost:1313 preview URL. Fold the existing "Local Development" and
"Build" content into this section.

Entrypoints — already present and correct in substance. Verify it opens by
stating the repo adheres to the
Scripts to Rule Them All
standard with that link (it does). Keep it where the canonical order puts it:
after Getting Started, before Rationale.

Rationale — why this exists. The Las Vegas Meshtastic/LoRa community needs
one durable, linkable place for channel configs and group links that does not
live inside a Discord or Signal thread.

Design — how it is structured. A single-page Hugo site; content in
content/_index.md; a minimal vendored theme in themes/loravega/ whose
baseof.html inlines static/css/style.css via readFile so the site ships
as one HTML document with no external CSS request; built to public/ by hugo --minify; deployed to Cloudflare Pages by .gitea/workflows/deploy.yml.

TODO — the policy requires a TODO section in the README. TODO.md already
exists at the root and is the live task list. Satisfy this by pointing at it:
a short section linking [TODO.md](TODO.md). Do not duplicate the task list in
two files — they will diverge.

Contributing — not a mandated section, but the existing content (contact
sneak@sneak.berlin for repo access) is useful and should not be dropped. Fold
it into Getting Started or keep it as an extra section; extra sections are
permitted, the required eight just have to be present.

Author — [@sneak](https://sneak.berlin). Must be the last section.

Also fix the stale claim in the current text: "The site is deployed
automatically via GitHub Actions." It is Gitea Actions, to Cloudflare Pages.

Definition of done

  1. README.md contains all of: a Description first line meeting the policy
    shape, ## Getting Started, ## Entrypoints, ## Rationale, ## Design,
    ## TODO, ## License, ## Author — with ## Author last.
  2. The Getting Started block is genuinely copy-pasteable and correct against
    the current Makefile targets.
  3. No content from the current README is silently lost: the contribute contact
    and the local-preview instructions survive somewhere.
  4. The "GitHub Actions" claim is corrected to Gitea Actions / Cloudflare Pages.
  5. make fmt has been run and make fmt-check passes (prettier, 4-space tabs,
    proseWrap: always, 80-column hard wrap).
  6. make check passes and script/cibuild succeeds.
  7. TODO.md updated in the same commit; the "Rework README.md into the
    standard sections" Future Steps entry is removed as completed.

Explicitly out of scope

  • The License section body. It is owned by #10, which is blocked on a decision.
    Leave it untouched here.
  • Adding a ## Quick Start section. The reference README in the prompts repo
    has one, but it is not in the required set and this repo is small enough that
    Getting Started covers it.

Ref: REPO_POLICIES.md README requirements; EXISTING_REPO_CHECKLIST.md.

## Problem `REPO_POLICIES.md` mandates a fixed set of README sections. This README has a different set, written before the standard was applied here. **Required:** Description, Getting Started, Entrypoints, Rationale, Design, TODO, License, Author. **Present:** About, Contributing, Technical Details (with Local Development and Build subsections), Entrypoints, License. So `Entrypoints` and `License` are correct; `Description`, `Getting Started`, `Rationale`, `Design`, `TODO`, and `Author` are all missing, and `About`, `Contributing`, and `Technical Details` are non-standard headings. ## Requirements **Description** — per policy, "First line must include the project name, purpose, category (web server, SPA, CLI tool, etc.), license, and author." The canonical form is the first prose line under the `# lora.vegas` title; a literal `## Description` heading is not required. Something of the shape: name, that it is a static site, the license, and `@sneak` as author. This depends on the license chosen in #10 — if #10 is not yet resolved, write the sentence without the license clause and leave the License section as-is; #10 will fill both in. Do not guess a license here. **Getting Started** — a copy-pasteable install/usage code block. For this repo that is the fresh-clone path: `make setup` then `make serve`, and the `http://localhost:1313` preview URL. Fold the existing "Local Development" and "Build" content into this section. **Entrypoints** — already present and correct in substance. Verify it opens by stating the repo adheres to the [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all) standard with that link (it does). Keep it where the canonical order puts it: after Getting Started, before Rationale. **Rationale** — why this exists. The Las Vegas Meshtastic/LoRa community needs one durable, linkable place for channel configs and group links that does not live inside a Discord or Signal thread. **Design** — how it is structured. A single-page Hugo site; content in `content/_index.md`; a minimal vendored theme in `themes/loravega/` whose `baseof.html` inlines `static/css/style.css` via `readFile` so the site ships as one HTML document with no external CSS request; built to `public/` by `hugo --minify`; deployed to Cloudflare Pages by `.gitea/workflows/deploy.yml`. **TODO** — the policy requires a TODO section in the README. `TODO.md` already exists at the root and is the live task list. Satisfy this by pointing at it: a short section linking `[TODO.md](TODO.md)`. Do not duplicate the task list in two files — they will diverge. **Contributing** — not a mandated section, but the existing content (contact sneak@sneak.berlin for repo access) is useful and should not be dropped. Fold it into Getting Started or keep it as an extra section; extra sections are permitted, the required eight just have to be present. **Author** — `[@sneak](https://sneak.berlin)`. Must be the last section. Also fix the stale claim in the current text: "The site is deployed automatically via GitHub Actions." It is Gitea Actions, to Cloudflare Pages. ## Definition of done 1. `README.md` contains all of: a Description first line meeting the policy shape, `## Getting Started`, `## Entrypoints`, `## Rationale`, `## Design`, `## TODO`, `## License`, `## Author` — with `## Author` last. 2. The Getting Started block is genuinely copy-pasteable and correct against the current `Makefile` targets. 3. No content from the current README is silently lost: the contribute contact and the local-preview instructions survive somewhere. 4. The "GitHub Actions" claim is corrected to Gitea Actions / Cloudflare Pages. 5. `make fmt` has been run and `make fmt-check` passes (prettier, 4-space tabs, `proseWrap: always`, 80-column hard wrap). 6. `make check` passes and `script/cibuild` succeeds. 7. `TODO.md` updated in the same commit; the "Rework README.md into the standard sections" Future Steps entry is removed as completed. ## Explicitly out of scope - The License section body. It is owned by #10, which is blocked on a decision. Leave it untouched here. - Adding a `## Quick Start` section. The reference README in the `prompts` repo has one, but it is not in the required set and this repo is small enough that Getting Started covers it. Ref: `REPO_POLICIES.md` README requirements; `EXISTING_REPO_CHECKLIST.md`.
clawbot commented 2026-08-09 18:33:01 +02:00
Author
Collaborator
Copy Link

Implementation plan

Branching from current main (0070fdb). Single commit, README.md +
TODO.md.

Target section order, ## Author last:

  1. Description — first prose line under # lora.vegas: name, that it is a
    single-page static Hugo site for the Las Vegas Meshtastic/LoRa community,
    and @sneak as author. No license clause — #10
    is unresolved, so per this issue's own instruction the sentence ships
    incomplete and #10 fills it in.
  2. Getting Started — fresh-clone block verified against the current
    Makefile, which declares exactly bootstrap setup test lint fmt fmt-check check docker hooks serve. So: git clone / cd / make setup /
    make serve, then http://localhost:1313. Note there is no make build target — the existing README's "Build: hugo" content maps to
    make test, which is hugo --minify writing to public/. Also folds in
    the contribute contact (sneak@sneak.berlin for repo access) so it is not
    lost.
  3. Entrypoints — moved to canonical position, opening sentence with the
    Scripts to Rule Them All
    link kept verbatim. One correction found while verifying it against the
    scripts: the script/fmt bullet still says "the repo's own top-level
    markdown docs", which #12 made
    false — script/fmt now runs prettier over '**/*.md' and '**/*.css'.
    The script/check order (test, lint, fmt-check) and the CHECK_EPOCH /
    bare-docker build paragraph are already accurate and stay.
  4. Rationale — one durable linkable home for channel configs and group
    links, rather than a Discord or Signal thread.
  5. Design — verified against the tree, not assumed: content/_index.md,
    themes/loravega/layouts/_default/baseof.html inlining
    themes/loravega/static/css/style.css via readFile ... | safeCSS,
    hugo --minify to public/, Cloudflare Pages via
    .gitea/workflows/deploy.yml.
  6. TODO — a short section linking [TODO.md](TODO.md), no duplication.
  7. License — heading moved to canonical position, body byte-for-byte
    untouched     ("Content is provided as-is for community use."). No LICENSE
    file added; that is #10's.
  8. Author — [@sneak](https://sneak.berlin), last.

Also fixes the stale "deployed automatically via GitHub Actions" claim: it is
Gitea Actions, publishing to Cloudflare Pages.

TODO.md: the "Rework README.md into the standard sections" Future Steps entry
is removed and a Completed Steps entry added, in the same commit.

Verification: make fmt, then make fmt-check, make check, and
script/cibuild with the check layer confirmed executed rather than CACHED.
Nothing outside README.md/TODO.md is touched, so the deploy path is
unaffected.

## Implementation plan Branching from current `main` (`0070fdb`). Single commit, `README.md` + `TODO.md`. Target section order, `## Author` last: 1. **Description** — first prose line under `# lora.vegas`: name, that it is a single-page static Hugo site for the Las Vegas Meshtastic/LoRa community, and `@sneak` as author. **No license clause** — https://git.eeqj.de/sneak/lora.vegas/issues/10 is unresolved, so per this issue's own instruction the sentence ships incomplete and #10 fills it in. 2. **Getting Started** — fresh-clone block verified against the current `Makefile`, which declares exactly `bootstrap setup test lint fmt fmt-check check docker hooks serve`. So: `git clone` / `cd` / `make setup` / `make serve`, then `http://localhost:1313`. Note there is **no** `make build` target — the existing README's "Build: `hugo`" content maps to `make test`, which is `hugo --minify` writing to `public/`. Also folds in the contribute contact (sneak@sneak.berlin for repo access) so it is not lost. 3. **Entrypoints** — moved to canonical position, opening sentence with the [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all) link kept verbatim. One correction found while verifying it against the scripts: the `script/fmt` bullet still says "the repo's own top-level markdown docs", which https://git.eeqj.de/sneak/lora.vegas/issues/12 made false — `script/fmt` now runs prettier over `'**/*.md'` and `'**/*.css'`. The `script/check` order (test, lint, fmt-check) and the `CHECK_EPOCH` / bare-`docker build` paragraph are already accurate and stay. 4. **Rationale** — one durable linkable home for channel configs and group links, rather than a Discord or Signal thread. 5. **Design** — verified against the tree, not assumed: `content/_index.md`, `themes/loravega/layouts/_default/baseof.html` inlining `themes/loravega/static/css/style.css` via `readFile ... | safeCSS`, `hugo --minify` to `public/`, Cloudflare Pages via `.gitea/workflows/deploy.yml`. 6. **TODO** — a short section linking `[TODO.md](TODO.md)`, no duplication. 7. **License** — heading moved to canonical position, **body byte-for-byte untouched** ("Content is provided as-is for community use."). No `LICENSE` file added; that is #10's. 8. **Author** — `[@sneak](https://sneak.berlin)`, last. Also fixes the stale "deployed automatically via GitHub Actions" claim: it is Gitea Actions, publishing to Cloudflare Pages. `TODO.md`: the "Rework README.md into the standard sections" Future Steps entry is removed and a Completed Steps entry added, in the same commit. Verification: `make fmt`, then `make fmt-check`, `make check`, and `script/cibuild` with the check layer confirmed executed rather than `CACHED`. Nothing outside `README.md`/`TODO.md` is touched, so the deploy path is unaffected.
clawbot commented 2026-08-09 18:35:11 +02:00
Author
Collaborator
Copy Link

Implemented in #35 (one commit,
9bfc37b).

All eight required sections are present in canonical order with ## Author
last, and the non-standard About / Contributing / Technical Details headings
are gone without losing what they held: the "what this site publishes" bullet
list moved under the Description, and the sneak@sneak.berlin contribute contact
plus the local-preview instructions moved into Getting Started.

Two corrections beyond the restructure itself:

  • The "deployed automatically via GitHub Actions" claim is now Gitea Actions
    publishing to Cloudflare Pages.
  • The script/fmt Entrypoints bullet still described the top-level-markdown
    scope that #12 replaced with
    '**/*.md' and '**/*.css'. The rest of Entrypoints checked out against the
    scripts, including the test/lint/fmt-check order and the CHECK_EPOCH guard
    paragraph.

Getting Started was written against the current Makefile rather than carried
over. Worth recording: there is no make build target, so the old
"Build: hugo" instruction became make test, and the old
"Local Development: hugo server" became make setup then make serve —
make setup is what puts the pinned Hugo on PATH in the first place, which the
old text never said.

License is untouched as instructed: heading in canonical position, body still
"Content is provided as-is for community use.", no LICENSE file added. The
Description sentence omits the license clause the policy asks for;
#10 completes both.

Verified: make fmt run and make fmt-check clean; make check green and
WARN-free; script/cibuild green with the make check layer genuinely
executed rather than served from cache (both hugo builds and the prettier check
appear in the layer's output), with the script/bootstrap layer above it still
cached as intended. TODO.md is updated in the same commit.

Implemented in https://git.eeqj.de/sneak/lora.vegas/pulls/35 (one commit, `9bfc37b`). All eight required sections are present in canonical order with `## Author` last, and the non-standard About / Contributing / Technical Details headings are gone without losing what they held: the "what this site publishes" bullet list moved under the Description, and the sneak@sneak.berlin contribute contact plus the local-preview instructions moved into Getting Started. Two corrections beyond the restructure itself: - The "deployed automatically via GitHub Actions" claim is now Gitea Actions publishing to Cloudflare Pages. - The `script/fmt` Entrypoints bullet still described the top-level-markdown scope that https://git.eeqj.de/sneak/lora.vegas/issues/12 replaced with `'**/*.md'` and `'**/*.css'`. The rest of Entrypoints checked out against the scripts, including the test/lint/fmt-check order and the `CHECK_EPOCH` guard paragraph. Getting Started was written against the current `Makefile` rather than carried over. Worth recording: there is no `make build` target, so the old "Build: `hugo`" instruction became `make test`, and the old "Local Development: `hugo server`" became `make setup` then `make serve` — `make setup` is what puts the pinned Hugo on PATH in the first place, which the old text never said. License is untouched as instructed: heading in canonical position, body still "Content is provided as-is for community use.", no `LICENSE` file added. The Description sentence omits the license clause the policy asks for; https://git.eeqj.de/sneak/lora.vegas/issues/10 completes both. Verified: `make fmt` run and `make fmt-check` clean; `make check` green and `WARN`-free; `script/cibuild` green with the `make check` layer genuinely executed rather than served from cache (both hugo builds and the prettier check appear in the layer's output), with the `script/bootstrap` layer above it still cached as intended. `TODO.md` is updated in the same commit.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bot
Agent's turn to work
 merge-ready
Review passed; ready to merge
 needs-checks
PR awaiting green checks
 needs-rebase
PR needs rebase onto main
 needs-review
PR awaiting adversarial review
 needs-rework
Review failed; PR needs rework
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
clawbot sneak
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sneak/lora.vegas#11
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?