Skip to content

Generate make help from the rules so the target list stops drifting #25

Description

@jamesx-improving

Summary

The repo documents its make targets in three places: the rules themselves (55),
a hand-written help: recipe of 46 @echo lines documenting 28
(Makefile:43–91), and four tables in the README documenting 21
(README.md:176–219). Neither doc is a superset of the other, and they have
already drifted. Generating the help output from ## description annotations on
the rules collapses the two hand-maintained copies into one that cannot go stale.

Raised by @currantw in review of #7:

Isn't this information already specified in the Makefile? Maybe worth just
pointing readers there so that this information only needs to be
specified/updated in one place?

Pointing the README at the Makefile alone does not achieve that, because the
Makefile's human-readable surface is help: — itself a hand-maintained copy, and
the less complete of the two.

Current Behavior

Three surfaces, maintained by hand:

Surface Targets documented
Rules in Makefile (source of truth) 55
help: recipe, 46 @echo lines (Makefile:43–91) 28
README "Make Targets", 4 tables (README.md:176–219) 21

Neither doc is a superset of the other. 14 targets appear in help: but not
the README (python-*, *-info, *-clean, server-start, clean, clobber,
config-editor-*); 7 appear in the README but not help: (benchmark-matrix,
benchmark-matrix-dry-run, benchmark-matrix-graphs, server-cluster-init,
test-scripts, test-scripts-all, test-scripts-e2e).

The test-scripts gap has bitten already. make help does not mention it, so
the only discoverable pointer to the Python test suite is the README — which is
how review of #7 ended up asking where those tests run.

Drift also reached the content, not just the coverage: the README's Testing table
claimed "99 Python unit tests (~12s)" and "all 108 tests" when the real numbers
were 180 and 189. Fixed in #7 by removing the hard-coded counts, but nothing
prevents the same class of staleness returning.

27 rules are documented nowhere: benchmark-matrix*, test-scripts*,
build-all, clean-all, test-all, java-info, java-run-cluster,
*-integration-test, ruby-unit-test, server-*-stop, server-cluster-init,
cluster-meet, cluster-slots, stop-6382, stop-26382, python-clean,
ruby-clean.

Proposed Behavior

Annotate each target that should be public with a ## description suffix, mark
sections with ##@ Name, and replace the help: recipe with a short awk pass
over $(MAKEFILE_LIST):

java-run: java-build ## Run Java benchmark (requires DRIVER and WORKLOAD)
	$(MAKE) java-run-nobuild

The README's four tables then reduce to a pointer at make help, leaving one
hand-maintained description per target, adjacent to the rule it describes.

Prototyped against the current branch: +34 / −71 lines, net −37 in the
Makefile — 46 @echo lines replaced by a 7-line recipe, 28 rule lines gaining a
suffix, 8 section markers. make help rendered all 28 targets correctly from the
annotations. Nothing in the repo asserts on help output (no test, no CI job, no
doc), so there are no other dependents.

Implementation Notes

  • Sequence this after Add Python benchmark engine (async valkey-glide, redis-py, valkey-py) #24. The Python engine PR edits the very @echo lines
    this change deletes — it rewrites the python-build and python-run help text
    — so deleting all 46 guarantees a conflict across the whole block. Land Add Python benchmark engine (async valkey-glide, redis-py, valkey-py) #24
    first. (Same collision hazard flagged in Build each engine once per sweep, not once per cell #3's notes.)
  • Ordering regresses unless rules are reordered. Today's help: is
    hand-ordered for readability (server-standalone-start before server-start).
    Generated output follows the Makefile's physical order, which in the prototype
    put clean and clobber in the middle of the server block. Either accept
    that, reorder the rules, or drive section grouping hard enough with ##@ that
    it stops mattering.
  • This fixes drift, not incompleteness. Generation guarantees no stale
    entries; it does not document the 27 targets that currently have none. Deciding
    which of those are public API and which are internal (stop-6382,
    cluster-meet, cluster-slots are plainly internal) is an editorial pass that
    should happen in the same PR, or the output will look arbitrary.
  • Behavior-preserving for every existing invocation. Only the help: recipe
    changes; no other target's prerequisites or commands move. Worth keeping the
    Examples: block at the end as literal @echo lines, since it documents a
    composed command line rather than a single target.
  • Watch the formatting details. Column alignment interacts awkwardly with
    ANSI colour codes — pad outside the escape sequences, or drop colour entirely
    and keep the output plain.
  • help is the default goal — it is the first rule and .DEFAULT_GOAL is
    unset, so bare make prints usage. Keep it first in the file (or set
    .DEFAULT_GOAL := help explicitly) and verify bare make after the change.

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

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions