Documentation, Branding, and Publishing

Updated

October 30, 2026

Documentation, Branding, and Publishing

A successful distribution requires clear documentation, recognizable visual branding, and reliable mirror publishing.

1. System Branding (/etc/os-release)

The systemd and freedesktop.org specification mandates /etc/os-release (and symlinked /usr/lib/os-release) to identify the operating system to utilities like neofetch, hostnamectl, and system tools:

# /etc/os-release
NAME="BYOL Linux"
PRETTY_NAME="BYOL Linux 1.0 (Rolling)"
ID=byol
ID_LIKE=alpine
VERSION="1.0"
VERSION_ID="1.0"
HOME_URL="https://github.com/kanthi/books"
SUPPORT_URL="https://github.com/kanthi/books/issues"
BUG_REPORT_URL="https://github.com/kanthi/books/issues"
LOGO="byol-logo"
ANSI_COLOR="0;34"

2. Issue Banner and Welcome MOTD

Configure /etc/issue to display a branded ASCII logo before the login prompt on virtual consoles:

       ____  __  ______  __ 
      / __ \/ / / / __ \/ / 
     / /_/ / /_/ / /_/ / /  
    / ____/\__, /\____/_/   
   /_/    /____/            
   BYOL Linux 1.0 (\l) - \m (\s \r)

3. Publishing Checksums and Signatures

When publishing your generated ISO to public web mirrors or GitHub releases, publish cryptographic checksums and signatures so users can verify download integrity:

# 1. Generate SHA256 and SHA512 checksums:
$ sha256sum byol-1.0-x86_64.iso > SHA256SUMS
$ sha512sum byol-1.0-x86_64.iso > SHA512SUMS

# 2. Cryptographically sign the checksums with your release key:
$ gpg --armor --detach-sign --output SHA256SUMS.sig SHA256SUMS

Users verify their download with a single command:

$ sha256sum -c SHA256SUMS
byol-1.0-x86_64.iso: OK

Your custom Linux distribution is now officially published!