Skip to content

Refresh README for FOSS professionalism and expanded audience #1353

Description

@ggfevans

Summary

Update the README to be more professional while keeping the project's tongue-in-cheek humour, and elevate Rackula's positioning as a FOSS project. This is the pre-release polish pass before the first CalVer-tagged release ships.

Motivation

The current README was written when Rackula was primarily a homelab tool. The project has since expanded to serve AV techs, IT students, and others. The README also buries self-hosting details (auth config, env vars) that belong in the Self-Hosting Guide, making the page too long and hard to scan.

Additionally, the CalVer cutover (#1802, #1315) and upcoming LXC deployment (#1211) require README updates to accurately represent versioning, badges, and new deployment options.

Changes

Structure & Tone

  • Add descriptive subtitle + flavour tagline
  • Add Features section with icon-prefixed bullets and a static screenshot (alongside existing GIF)
  • Add "Who It's For" use case section
  • Add contributing callout with good-first-issue link
  • Move "Built With Claude" up as a differentiator
  • Condense Acknowledgements to one-liner + link
  • Tone: hybrid — professional structure with fun copy (keep personality, make it scannable)

Badges

  • Keep License, GitHub Release, and Docker badges (work fine with CalVer)
  • Add CalVer badge (signals versioning scheme at a glance)
  • Replace coverage / test-ratio / test-time badges with a CI status badge (cleaner hero, less stale-looking)
  • Preserve Star History

Deployment

  • Add LXC deployment section — Proxmox community-scripts one-liner + manual install option
  • Move deployment config details (auth env vars, CORS, cookie settings) to Self-Hosting Guide (link only in README)
  • Keep Docker Run and Docker Compose sections

Links & Metadata

  • Add GitHub Discussions link
  • Add Changelog link (CHANGELOG.md)
  • Move Documentation section higher
  • Update copyright to 2025–2026 Gareth Evans

Versioning Accuracy

Design Document

See docs/plans/2026-02-27-readme-refresh-design.md (committed on branch).

Acceptance Criteria

  • README follows hybrid tone (professional structure, fun copy)
  • Features section with static screenshot added
  • CalVer badge added
  • Coverage badges replaced with CI status badge
  • LXC deployment section added (community-scripts one-liner + manual option)
  • Auth config details moved to Self-Hosting Guide (README links to docs)
  • GitHub Discussions link added
  • Changelog link added
  • Copyright updated to 2025–2026
  • Existing badges (License, Release, Docker) and Star History preserved
  • All deployment config removed from README (linked to Self-Hosting Guide)

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions