docs(cache): write down the producer half of the depended-upon names contract
daniel/gitdan's ci-cache-reclaim.sh hard-codes four dot-prefixed names it reads to make correctness decisions but never reclaims as leftovers — .ci-lock-*, .cache-last-used, .gitea-last-used, .ci-keep — none of which carried a matching note here (gitdan#32, the follow-up shape to #28/#30 that #7/PR #8 covered for the leftover names specifically). Of the four, this repo actually produces two: - .ci-lock-<id>, written by scripts/cache-lock.sh (acquire/release) and cache-lib.sh's write_cache_lock(). Documents the contract at cache-lock.sh's header, the site someone renaming the marker would most likely be editing. - .cache-last-used, stamped every run by cargo-cache/action.yml. Documents the contract at the exact line that writes it. The other two are read by gitdan's script but produced by nothing in this repo: .gitea-last-used is a legacy naming convention individual repos used before adopting the shared cargo-cache action (nothing here writes it today), and .ci-keep is a per-repo, hand-placed opt-out any consuming repo's own workflow may drop directly into a cache directory, with no single owner. Both get a paragraph in README.md's new subsection explaining why no producer-side counterpart exists for them, rather than inventing an owner this repo doesn't have. README.md's "Scratch names in a cache root are a cross-repo contract" section gains a new subsection, "Names this repo doesn't reclaim, but the arbiter depends on", covering all four and pointing at gitdan's DEPENDED-UPON NAMES CONTRACT block as the canonical description. No behaviour change: comments and docs only. Ref: gitdan#32. Consumer-side counterpart: daniel/gitdan (this branch's sibling PR). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MJHKJFJVUjnvVsemVBnvrd
This commit is contained in:
@@ -165,6 +165,14 @@ runs:
|
||||
# touched unconditionally every run: a run that hits the cache for every
|
||||
# crate may write nothing at all inside the tree, which would make a
|
||||
# just-used directory look stale to the eviction pass.
|
||||
#
|
||||
# `.cache-last-used` IS A CROSS-REPO CONTRACT NAME with daniel/gitdan's
|
||||
# `scripts/ci-cache-reclaim.sh`, which reads this exact marker for its own
|
||||
# LRU ordering and to recognise a directory as a cache dir at all. Rename
|
||||
# it here without a matching change there and that script silently falls
|
||||
# back to directory mtime for both — see README.md's "Scratch names in a
|
||||
# cache root" section and the `DEPENDED-UPON NAMES CONTRACT` block in
|
||||
# gitdan's script.
|
||||
- shell: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
Reference in New Issue
Block a user