You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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.
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.
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.
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.
Summary
The repo documents its make targets in three places: the rules themselves (55),
a hand-written
help:recipe of 46@echolines 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 havealready drifted. Generating the help output from
## descriptionannotations onthe rules collapses the two hand-maintained copies into one that cannot go stale.
Raised by @currantw in review of #7:
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, andthe less complete of the two.
Current Behavior
Three surfaces, maintained by hand:
Makefile(source of truth)help:recipe, 46@echolines (Makefile:43–91)README.md:176–219)Neither doc is a superset of the other. 14 targets appear in
help:but notthe README (
python-*,*-info,*-clean,server-start,clean,clobber,config-editor-*); 7 appear in the README but nothelp:(benchmark-matrix,benchmark-matrix-dry-run,benchmark-matrix-graphs,server-cluster-init,test-scripts,test-scripts-all,test-scripts-e2e).The
test-scriptsgap has bitten already.make helpdoes not mention it, sothe 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
## descriptionsuffix, marksections with
##@ Name, and replace thehelp:recipe with a shortawkpassover
$(MAKEFILE_LIST):The README's four tables then reduce to a pointer at
make help, leaving onehand-maintained description per target, adjacent to the rule it describes.
Prototyped against the current branch: +34 / −71 lines, net −37 in the
Makefile — 46
@echolines replaced by a 7-line recipe, 28 rule lines gaining asuffix, 8 section markers.
make helprendered all 28 targets correctly from theannotations. Nothing in the repo asserts on help output (no test, no CI job, no
doc), so there are no other dependents.
Implementation Notes
@echolinesthis change deletes — it rewrites the
python-buildandpython-runhelp 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.)
help:ishand-ordered for readability (
server-standalone-startbeforeserver-start).Generated output follows the Makefile's physical order, which in the prototype
put
cleanandclobberin the middle of the server block. Either acceptthat, reorder the rules, or drive section grouping hard enough with
##@thatit stops mattering.
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-slotsare plainly internal) is an editorial pass thatshould happen in the same PR, or the output will look arbitrary.
help:recipechanges; no other target's prerequisites or commands move. Worth keeping the
Examples:block at the end as literal@echolines, since it documents acomposed command line rather than a single target.
ANSI colour codes — pad outside the escape sequences, or drop colour entirely
and keep the output plain.
helpis the default goal — it is the first rule and.DEFAULT_GOALisunset, so bare
makeprints usage. Keep it first in the file (or set.DEFAULT_GOAL := helpexplicitly) and verify baremakeafter the change.