docs: use $ARC_VERSION in docker-compose.yml image comments - #238
docs: use $ARC_VERSION in docker-compose.yml image comments#238teyrebaz33 wants to merge 1 commit into
Conversation
52028c7 to
d2b0392
Compare
osr21
left a comment
There was a problem hiding this comment.
This does the better of the two fixes discussed on #235 — $ARC_VERSION instead of a fresh literal tag takes these comments out of the goes-stale-every-release class entirely (a 0.7.3 bump would have re-armed the same bug for v0.8.0), and it now matches the exact spelling docs/running-an-arc-node.md uses in its Docker section, which is the doc this very header points at. The reader flow works end-to-end: the header says "see running-an-arc-node.md#docker", and that doc is where ARC_VERSION gets exported before these two variables are set. Verified these were the last 0.6.0 references under deployments/, so the directory is clean after this lands.
Two small asks, neither about the diff itself:
1. Retitle and fix the body — they describe the change you didn't make. The title says "update image comments to v0.7.3" and the body says "updated both to 0.7.3", but the diff (correctly!) contains no 0.7.3 anywhere. Whoever reads the merge commit or git log later will look for a version bump that isn't there — and, worse, the next release's "grep the repo for stale versions" audit may skip this file believing it pins 0.7.3. Something like "docs: use $ARC_VERSION in docker-compose.yml image comments" describes what actually landed and advertises the anti-drift pattern to the next doc author.
2. Optional, one line: anchor $ARC_VERSION for the reader who starts here. Someone who opens the compose file first (rather than arriving from the doc) meets an undefined variable in an example. A parenthetical on either line — e.g. :$ARC_VERSION (current release; see the Versions table in docs/installation.md)` — closes that loop for the cost of a few words. Take or leave; the doc link in the line above these already covers the diligent reader.
Approving as-is since both points are commit-message/polish, not correctness — but please do the retitle before merge; inaccurate history on a docs fix is how the next staleness audit goes wrong.
Follow the pattern already used in docs/running-an-arc-node.md instead of a literal version tag, so this comment doesn't go stale again on the next release. Also anchor $ARC_VERSION with a pointer to the Versions table for readers who open this file directly. Suggested by @osr21 in review on circlefin#235.
d2b0392 to
985ec58
Compare
osr21
left a comment
There was a problem hiding this comment.
Re-approving at 985ec585 — the push after my earlier review resolves everything flagged:
- Title and body now describe the actual diff (
$ARC_VERSIONsubstitution, not a tag bump), so the merge commit will tell the next staleness audit the truth. - The inline pointer (
current release listed in the Versions table in docs/installation.md) closes the last gap: a reader who opens the compose file cold now gets both the drift-proof example and the authoritative place to resolve it, without needing to arrive via the doc link.
One observation, zero action needed: the pointer names docs/installation.md's Versions table, which is the same single source of truth #226 just corrected — so all three files in this staleness family (installation.md, running-an-arc-node.md, docker-compose.yml) now converge on one table. That's the "single source of truth" outcome the #225/#226 discussion was circling, achieved incrementally. Nothing left here from my side; LGTM.
Uses $ARC_VERSION instead of a literal tag in the two image comment examples in deployments/docker-compose.yml, matching the pattern in docs/running-an-arc-node.md#docker (which this file's header already points to). Avoids re-arming the same staleness issue on the next release. See discussion on #235.