Skip to content

Restructure the README to the portfolio standard - #7

Open
adamXbot wants to merge 1 commit into
mainfrom
docs/readme-standard
Open

Restructure the README to the portfolio standard#7
adamXbot wants to merge 1 commit into
mainfrom
docs/readme-standard

Conversation

@adamXbot

@adamXbot adamXbot commented Aug 9, 2026

Copy link
Copy Markdown
Owner

Brings this README into line with the layout every other repo in the portfolio is moving to: hero, badge row, disclosure block, then overview / what it does / get it / docs / contributing / licence.

Wrong facts removed

  • "Set schedules to clean hourly, daily, or on-demand." Not what the code does. ScheduleInterval offers every 1, 2, 4, 8, 12 or 24 hours, or manual only. Corrected.
  • The ## Install section implied the Homebrew cask is current. It is not: adamxbot/homebrew-tap is serving 0.0.2 while the latest release here is v0.0.3. The README still points at the tap as the normal install path, but now says so plainly so nobody wonders why they got an old build.
  • Feature list was materially incomplete. It omitted the dry run (DryRun.swift), the self-test (SelfTest.swift), the pre-clean APFS snapshot (SnapshotService.swift), the PathSafety guardrails, and the fact that unattended scheduled runs downgrade "Lock with Immutable File" to a plain wipe unless allowAggressiveScheduledClean is on. All added, all verified against source.
  • Target counts were unstated. Now taken from the registry: 8 basic, 10 strong, 8 paranoid, 26 total.
  • MARKETING_VERSION in project.yml reads 1.0.1, which does not match any published release. Nothing in the new README claims 1.0 — the disclosure uses the pre-1.0 variant, matching the actual latest release of v0.0.3. Worth fixing in project.yml separately; the release workflow will refuse to publish a tag that disagrees with it.
  • Removed the ## Cutting a release and ## Auto-updates (Sparkle) sections, which duplicated docs/RELEASES.md and had begun to drift from it. The README now links there instead, and states accurately that Sparkle is dormant (SUFeedURL and SUPublicEDKey are absent from Info.plist, there is no gh-pages branch, and https://adamxbot.github.io/BananaBlitz/appcast.xml currently 404s — so that URL is deliberately not linked from the README).

Links

Every link in the new files was checked. All relative paths exist; every external URL returns 200, including the user-attachments screenshot, which was preserved and moved rather than dropped.

Badges

Status, release, licence and CI. Release renders v0.0.3, licence renders MIT, and CI renders passingci.yml does run on pushes to main and has runs there. The status badge renders "resource not found" until the status hub PR merges; the path is correct and it will resolve then.

Content moved, not deleted

  • Build requirements, XcodeGen usage, the test command, the coverage table, the just recipes and the bundled-script inventory → new CONTRIBUTING.md
  • Reverting, recovery-script regeneration, snapshots, and the Full Disk Access requirement → new docs/RECOVERY.md
  • The manual Finder locking walkthrough and its image → new docs/MANUAL-LOCKING.md

The destructive-operations [!CAUTION] block is kept verbatim as a separate block below the disclosure. It makes a different claim from the stability warning and has not been merged into it.

Size

README 5716 → 6365 bytes.

Reorders the README into the shared product layout (hero, badges,
disclosure, overview, what it does, get it, docs, contributing,
licence) and moves the contributor-facing detail into named files.

Corrections:
- "clean hourly, daily, or on-demand" was wrong. ScheduleInterval
  offers 1, 2, 4, 8, 12 and 24 hours, or manual only.
- The feature list omitted the dry run, the self-test, the snapshot,
  the PathSafety guardrails and the unattended-run downgrade, all of
  which exist in the source.
- Target counts are now stated from the registry: 8 basic, 10 strong,
  8 paranoid, 26 total.
- Added a note that the Homebrew tap is serving 0.0.2 while the latest
  release is v0.0.3, rather than implying the cask is current.
- "License"/"behavior" -> "Licence"/"behaviour" for consistency with
  the rest of the portfolio.

Moved out of the README (nothing deleted):
- build requirements, XcodeGen usage, the test command and coverage
  table, the just recipes and the script inventory -> CONTRIBUTING.md
- reverting, recovery-script regeneration, snapshots and the Full Disk
  Access requirement -> docs/RECOVERY.md
- the manual Finder locking walkthrough and its image
  -> docs/MANUAL-LOCKING.md
- the "Cutting a release" and Sparkle setup sections, which duplicated
  docs/RELEASES.md, are now a link to it

The destructive-operations CAUTION is kept verbatim as a separate block
below the disclosure; it makes a different claim and is not merged in.

Badges: status, release, licence and CI. All four URLs were checked;
release, licence and CI resolve. README 5716 -> 6365 bytes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant