DRIVERS-3588: Add Claude Code skill for retiring EOL server version references - #1970
Conversation
…ferences Adds a reusable skill (.claude/skills/retiring-server-versions/SKILL.md) documenting a repeatable process for finding and removing dead version-gated tests, prose, and pseudocode after the minimum supported MongoDB server version is raised. Distilled from the DRIVERS-3439 pre-4.2 cleanup, which took many review rounds to find all the ways dead version references hide in this repo (vacuous "at-floor" qualifiers, wire-version-only phrasing, stale illustrative examples, unrunnable YAML tests gated by maxServerVersion, stale generated-file naming, etc.). Includes tested, verified grep/find/awk commands for each pattern shape. Validated by running it in dry-run/discovery mode against a hypothetical 4.2-to-4.4 retirement in this repo (no edits made), and refined through two rounds of independent critical review.
There was a problem hiding this comment.
Pull request overview
Adds a new Claude Code skill documenting a repeatable, repo-wide process for cleaning up dead version-gated content after raising the minimum supported MongoDB server version in the specifications repository.
Changes:
- Introduces a step-by-step workflow for determining scope, setting fix/leave criteria, and iterating on repo-wide sweeps.
- Provides a catalog of search “shapes” (regexes/commands) to uncover common hidden EOL-version references across Markdown and YAML tests.
- Documents operational practices (batching, regeneration guidance, and verification against real driver implementations).
Comments suppressed due to low confidence (2)
.claude/skills/retiring-server-versions/SKILL.md:156
- Same issue here:
\bis not a word-boundary ingrep -Eon common grep implementations, so this command can silently fail to match. Use a digit-boundary like([^0-9]|$)instead (or switch to a tool/flag that supports\b).
grep -rnE "(wire ?[Vv]ersion|[Mm]ax[Ww]ireVersion|[Mm]in[Ww]ireVersion)['\"]? *(is |>=? ?|<=? ?|of |as )?9\b" source --include="*.md"
.claude/skills/retiring-server-versions/SKILL.md:235
- Similarly here:
\sisn't a whitespace metacharacter forgrep -Eon common implementations, so the blockquote branch of this pattern may not work. Prefer[[:space:]]*(or a literal space) for portability.
grep -rnE '"[^"]*4\.2[^"]*"|>\s*".*4\.2' source --include="*.md"
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| description: >- | ||
| Use when raising the minimum supported MongoDB server version in this repository (e.g. EOL'ing an old server | ||
| version) and needing to find and remove now-dead version-gated tests, prose, and pseudocode across the whole | ||
| specifications repo. |
There was a problem hiding this comment.
| specifications repo. | |
| specifications repo. | |
| disable-model-invocation: true |
Suggest making it an explicitly envoked skill to reduce context costs.
https://code.claude.com/docs/en/features-overview#context-cost-by-feature
By default, skill descriptions load at session start so Claude can decide when to use them. Set
disable-model-invocation: truein a skill’s frontmatter to hide it from Claude entirely until you invoke it manually. This reduces context cost to zero for skills you only trigger yourself. For a skill you didn’t write, set skillOverrides in settings to do the same without editing its file.
There was a problem hiding this comment.
I worry that the skill will go unnoticed and unused as a result. How to weigh the tradeoff?
There was a problem hiding this comment.
How much is the actual cost of the description being loaded here? The three lines of description text shouldn't add anything beyond a rounding error to the total context.
There was a problem hiding this comment.
The cost is low, and there aren't many skills in this repo. I'm going to decline this one, as I think the tradeoff of someone not noticing the skill and being told of it outweighs the extra context.
kevinAlbs
left a comment
kevinAlbs
left a comment
There was a problem hiding this comment.
LGTM with minor suggestions.
I was mildly concerned that the skill itself is a lot of content to maintain. But I think the skill can be liberally updated, as it is intended to help development, not provide user-facing documentation.
Review feedback:
- Note the cleanup is only expected once all drivers have dropped the old
server version. Drivers tracking this repo via a git submodule pick up
test deletions on their next bump, so removing tests before the EOL
silently drops their coverage.
- Correct the regeneration guidance: `make -C source` only converts
.yml to .json and does not process .template files. Point at the
generator scripts in .github/workflows/unified-tests.yml, which is
also what regenerates these files in CI.
- Drop exact search-hit counts, which go stale quickly, keeping the
qualitative comparisons that motivate each scoped pattern.
- Add an AGENTS.md pointer to the skill, so it is discoverable from the
always-loaded project instructions as well as by model invocation.
Make the patterns work for future retirements (one version at a time,
including 5.0 and later):
- Scope the table-cell search to the two versions in play instead of a
[2-4] digit range. The range re-surfaces prior retirements and cannot
match 5.0 or later at all, so it would have failed silently.
- Search both wire versions, and document that wire numbers go
multi-digit at 5.0 (wire 13) and have gaps (4.4->5.0 skips 10-12,
6.2->7.0 skips 20), so they must be looked up, never computed.
- Note that the multi-digit collision guarantee expires once the server
reaches double-digit majors, with the left guard to add when it does.
- Widen the undotted identifier quantifier to {2,} so it still matches
once versions reach three undotted digits.
Found while testing the commands against hypothetical 4.2, 5.0 and 8.0
retirements:
- Add tests/invalid/ schema fixtures to the LEAVE list. They hardcode
versions below every conceivable floor to prove the schema rejects
them, so they match the maxServerVersion sweep on every retirement.
- Note that the wire version table lags the server (no 9.0 row today),
and how to sanity-check a zero-hit wire version search.
80d0902 to
ec24dd5
Compare
|
All comments addressed. Also fixed some other issues while testing the skill against 5.0 and 8.0. |
Adds a reusable skill (.claude/skills/retiring-server-versions/SKILL.md) documenting a repeatable process for finding and removing dead version-gated tests, prose, and pseudocode after the minimum supported MongoDB server version is raised.
Distilled from the DRIVERS-3439 pre-4.2 cleanup, which took many review rounds to find all the ways dead version references hide in this repo. Includes tested, verified grep/find/awk commands for each pattern shape.
Validated by running it in dry-run/discovery mode against a hypothetical 4.2-to-4.4 retirement in this repo (no edits made), and refined through two rounds of independent critical review.
Please complete the following before merging:
Is the relevant DRIVERS ticket in the PR title?
[N/A] Update changelog.
[N/A] Test changes in at least one language driver.
[N/A] Test these changes against all server versions and topologies (including standalone, replica set, and sharded
clusters).