Repository navigation
Overhaul README and website to present Pace as a distributed compile cluster #1729
Copy link
Copy link
Open
Labels
Description
Problem
The project's front doors still describe what Pace was, not what it is. Pace started as a memcached/Redis-compatible
key/value daemon with a compile cache on top. Today the product is a distributed compile cluster:
- a portable compile cache (
pace-cc); - a fleet of compile nodes (
pace-node) with a Raft-backed scheduler, LAN discovery, enrollment and
identity-key membership; - an operator client (
pacectl), with live stats and a fleet dashboard.
The key/value daemon is now one component of that, not the headline.
As of fd64ef32:
README.md.- It opens with "Three things ship from this repository" and leads with
pace-kvand its four wire protocols. It
benchmarks against memcached/Redis before it says anything about distributing a build. pace-nodeis introduced as "an optional compile worker".- The cluster is not mentioned in the opening at all: consensus, leader scheduling, discovery, enrollment,
membership, the fleet page and live stats. - Section order: Install → Quick start: the cache daemon → Quick start: caching your compiles → sccache backend →
…. The first hands-on section a reader meets is about running a memcached replacement.
- It opens with "Three things ship from this repository" and leads with
- The website (
docs/index.md,mkdocs.yml).docs/index.mdopens with "Pace's pace-kv is a cache daemon that speaks four wire protocols". Its "What's in
the box" lists only memcached/Redis features.site_descriptionis "A memcached- and Redis-compatible cache daemon, and a portable compile cache". It doesn't
mention distribution.- In
nav:, Protocols (12 pages) and Commands (one page per memcached/Redis verb) sit at the top level beside
Getting started, ahead of anything about the fleet. Cluster topics are spread across Getting started
(Distributed compilation, Cluster discovery) and Tools.
A new reader, or someone evaluating Pace against sccache/distcc/icecream/Bazel remote execution, comes away thinking
it is a memcached clone with a compiler wrapper.
Proposal
Rewrite the README and the site landing page around the current focus, and restructure the navigation to match.
- One-sentence positioning. Something in the spirit of "a distributed compile cluster for C/C++: a portable
compile cache plus a self-organising fleet of compile nodes". Use it consistently in:- the README's opening;
docs/index.md;site_description;- the GitHub repository description.
- README order.
- What it is and who it's for (teams building large C++ trees across CI and workstations).
- What you get:
- cache hits across checkout paths;
- misses distributed across the fleet;
- nodes that find each other and elect a scheduler;
- one operator view.
- Quick start: a single workstation, then a fleet of two or more machines.
- How it compares to ccache/sccache/distcc/icecream (honest, short).
- Then the components (
pace-cc,pace-node,pacectl,pace-kv), withpace-kvpresented as the cache
tier, and its memcached/Redis/sccache-backend use as a secondary capability. - Benchmarks, deployment, configuration and contributing, kept or moved to the site.
- Website.
- A landing page with the same positioning, plus an architecture picture: launcher → local node → leader
scheduler → workers, and the cache tiers. - Group the fleet material under its own top-level section: distributed compilation, discovery, enrollment and
membership, scheduling, observability (fleet page,pacectl live-stats), operations. - Move Protocols and Commands under a "pace-kv reference" (or similar) section, so they stay complete but no
longer frame the product.
- A landing page with the same positioning, plus an architecture picture: launcher → local node → leader
- Keep what is true and useful.
- Don't delete the protocol and command reference. It stays accurate for
pace-kvusers. - Keep the fastcached → Pace upgrade note, but move it down from the README's first lines.
- Don't delete the protocol and command reference. It stays accurate for
Non-goals
- No new features, and no change to behaviour or to any CLI.
- No rewrite of the reference pages' content beyond the moves and the links that change because of them.
Acceptance
- The README's first screen (opening plus first section) describes Pace as a distributed compile cluster. Its first
quick start is a compile cache plus a fleet, not the key/value daemon. docs/index.md,site_descriptionand the repository description use the same positioning sentence.- The site's top-level navigation puts the compile cluster first. The memcached/Redis protocol and command pages
live under apace-kvreference section. mkdocs build --strictpasses (docs.yml), every moved page keeps working links, and the docs-subject checks
(ctest -L docs-subject) pass.
Reactions are currently unavailable
Activity