OpenRiot v6.2 — Readable

“The best documentation is the kind you actually read.” — Someone who never used man grep

Release Overview

OpenRiot v6.2 fixes the most embarrassing UI mistake in recent memory: the release notes display. We spent hours crafting beautiful markdown release notes for v6.1, then piped them through less — a tool designed for reading kernel panics, not human prose.

The result? A screen full of ~ tildes. An (END) prompt that confuses everyone. A : command line that looks like a shell prompt. Users had no idea the release notes were even there, let alone how to read them.

Total changes: one custom pager, native termios, an ask prompt, and one dead dependency removed.

📖 Release Notes: Now Actually Readable

The Problem: less is a file viewer, not a release notes renderer. It shows tildes for empty lines, prints (END) at the bottom, and drops you into a command mode with : that looks like a broken terminal. Users saw a wall of ~ and thought the installer had crashed.

The Fix: Replaced less with a custom Go pager that:

Reads terminal height via golang.org/x/sys/unix.IoctlGetWinsize — no stty shell-out
Sets raw mode via unix.IoctlGetTermios / unix.IoctlSetTermios — single-key input without pressing ENTER
Prints one screen of content at a time — no tildes, no (END), no :
Prompts with -- More -- (press any key to continue, q to quit) — plain English
Quits immediately on q, continues on any other key
Returns to normal shell prompt when done — no mode confusion

Implementation:

pageSize := terminalHeight() - 3  // header + footer + prompt
readKey("-- More -- (press any key to continue, q to quit)")

golang.org/x/sys/unix is already a dependency. No new packages. No stty. No less.

“If your release notes need a man page to explain how to read them, you have failed.”

🔔 Ask Before Showing

The Problem: Release notes blasted onto the screen the moment install finished, scrolling past the final status lines before the user could read them. There was no choice — you got the notes whether you wanted them or not.

The Fix: The installer now asks:

[ASK] Read v6.2 Release Notes? [Y/n]

Defaults to yes (press Y, y, or Enter). Press N, n, Q, or q to skip. If the release notes file is missing, the question is skipped silently.

The prompt uses the same readKey() raw-mode logic as the pager itself, so it works with a single keystroke — no ENTER required.

📐 Page Size Accounting

The Problem: The first page of release notes included the header (====, title, ====) and the last page included the footer, but the page-size math only subtracted room for the prompt. Result: the footer or final lines scrolled off-screen.

The Fix: Header and footer lines are now part of the content slice that gets paginated. pageSize = terminalHeight() - 3 correctly accounts for the blank line, prompt, and keypress newline between pages.

📦 Package Changes

Added: lowdown — OpenBSD-native markdown renderer for terminal output
Removed: less as a runtime dependency for release notes (still in base system)
Removed: stty shell-outs — replaced with native Go termios
New: docs/* deployed to ~/.local/share/openriot/docs/ during install

🧾 Files Changed

File	Nature of Change
`source/installer/release_notes.go`	Custom pager with native termios
`source/commands/helpers.go`	Calls `AskShowReleaseNotes()` at end
`install/packages.yaml`	Added `lowdown`, docs deployment
`AGENTS.md`	Added release notes requirements
`docs/v6.2-Release-Notes.md`	This file

🗣️ Final Words

“v6.0 was about beauty. v6.1 was about correctness. v6.2 is about not being so clever that you forget how normal people think.”

This release is dedicated to everyone who ever ran openriot --install, saw a wall of tildes, and immediately ran kill -9 because they thought the installer had hung. We see you. We understand. And we’re sorry.

The release notes are now readable by humans. What a concept.

Upgrade with the usual command:

curl -fsSL https://OpenRiot.org/setup.sh | sh

— The OpenRiot Crew

“Good software is invisible. Bad software is a pager you need a manual to exit.”