Skip to content

Overhaul README and website to present Pace as a distributed compile cluster #1729

Open

Description

@christianparpart

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-kv and its four wire protocols. It
      benchmarks against memcached/Redis before it says anything about distributing a build.
    • pace-node is 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.
  • The website (docs/index.md, mkdocs.yml).
    • docs/index.md opens 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_description is "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.

  1. 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.
  2. README order.
    1. What it is and who it's for (teams building large C++ trees across CI and workstations).
    2. 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.
    3. Quick start: a single workstation, then a fleet of two or more machines.
    4. How it compares to ccache/sccache/distcc/icecream (honest, short).
    5. Then the components (pace-cc, pace-node, pacectl, pace-kv), with pace-kv presented as the cache
      tier, and its memcached/Redis/sccache-backend use as a secondary capability.
    6. Benchmarks, deployment, configuration and contributing, kept or moved to the site.
  3. 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.
  4. Keep what is true and useful.
    • Don't delete the protocol and command reference. It stays accurate for pace-kv users.
    • Keep the fastcached → Pace upgrade note, but move it down from the README's first lines.

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_description and 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 a pace-kv reference section.
  • mkdocs build --strict passes (docs.yml), every moved page keeps working links, and the docs-subject checks
    (ctest -L docs-subject) pass.
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

    area/docstype/docsdocs/, site/, help text, the rulebook

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions