docs: add driver client/exporter compatibility rule

[mangelajo]

Summary

Adds a new project rule, .claude/rules/driver-compatibility.md (stored as .cursor/rules/driver-compatibility.mdc and symlinked, matching the existing pattern), and indexes it in CLAUDE.md.

It documents the backwards-compatibility invariants between independently-released clients and exporters, so future driver changes — human or AI-assisted — don't break mixed-version deployments:

• client() class path stability: the exporter reports this string and the client imports it from its own environment. Changing it for a released driver breaks old clients with ImportError — a failure mode invisible to unit tests. New drivers must always override client() explicitly.
• Stable wire surfaces: RPC method names/argument shapes and the ClientStreamResource / PresignedRequestResource handle types handled by Driver.resource().
• Client API deprecation policy: deprecate public method parameters before removing them; keep j CLI commands and flags stable.
• Dependency pinning: released sdists exact-pin jumpstarter* deps via hatch-pin-jumpstarter, so no manual bounds in pyproject.toml.
• Opendal migration checklist: the pattern established in Remove opendal dependency from QEMU driver #535 for removing opendal from the remaining drivers (Remove opendal dependency, preserve exporter-side presigned downloads #441), including the operator= kwarg migration note for release notes.
• Testing expectations: end-to-end tests via jumpstarter.common.utils.serve when touching file-transfer paths.

Why

While reviewing #535 (QEMU opendal removal), it turned out the migration was cross-version safe only because QemuFlasher explicitly overrides client() — drivers relying on a base-class default would have silently started reporting a class path that old clients can't import. With more drivers queued for the opendal removal series (#441), this invariant should be written down before the next migration rather than rediscovered.

Notes for reviewers

• Doc-only change; no code is touched.
• Two judgement calls worth a look: the deprecation policy (one release of warnings before removing a public client API parameter) is proposed here as project policy — adjust if you want a different commitment; and the opendal checklist lives in this rule rather than in Remove opendal dependency, preserve exporter-side presigned downloads #441 because it's only actionable next to the client() invariant that makes migrations safe.

Related #441

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR establishes driver compatibility rules for maintaining interoperability between independently released exporter and client packages. It creates a new rule file documenting stability invariants around class paths, wire protocols, versioning, and testing, then registers it in the project documentation.

Changes

Driver Compatibility Rules

Layer / File(s)	Summary
Driver compatibility rule definition \.cursor/rules/driver-compatibility.mdc	Establishes critical invariants: the exporter's client() class-path string must never change for released drivers (to prevent ImportError in mixed-version deployments); RPC method names and argument shapes must remain backward-compatible; only existing resource handle types (ClientStreamResource, PresignedRequestResource) are allowed; client API parameters should deprecate before removal; j CLI command names and flags must stay stable; version pinning must use build hooks, not manual pyproject.toml bounds; opendal migration must preserve class paths and RPC signatures while moving to core interfaces; end-to-end tests using the in-process harness must cover real client→exporter resource flows.
Rule registration and navigation \.claude/rules/driver-compatibility.md, CLAUDE.md	Symlink from .claude/rules/driver-compatibility.md points to the new rule file for discovery. CLAUDE.md is updated to list the new driver-compatibility rule and add a bullet instructing developers to consult it when changing driver/client interfaces.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• jumpstarter-dev/jumpstarter#107: Updates project .claude rules infrastructure by adding symlink-style rule references and adjusting CLAUDE.md for rule navigation, overlapping in the rule-discovery pattern.

Suggested reviewers

• kirkbrauer
• bkhizgiy
• bennyz

Poem

🐰 A rulebook for drivers, so steady and true,
Symlinks point homeward—no paths left askew,
Class names must linger, RPC signatures stay,
While clients and exporters dance 'cross the fray! 🚀

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: add driver client/exporter compatibility rule' directly and clearly describes the main change: adding a new documentation rule file about driver compatibility.
Description check	✅ Passed	The description is well-structured, directly related to the changeset, and explains the purpose, content, and context of the new rule documentation being added.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/driver-compatibility-rule

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

.cursor/rules/driver-compatibility.mdc (1)

45-46: Update deprecation-window reviewer judgment guidance

.cursor/rules/driver-compatibility.mdc already mandates “warn/ignore for at least one release” plus documenting the removals and migration path in release notes, so the “one-release is a reviewer judgment point” framing isn’t supported by the repo context.

If this PR is actually deprecating/removing a public client parameter, align the implementation with that rule and ensure the eventual removal + migration notes are included (existing warnings.warn(...) patterns exist, e.g. python/packages/jumpstarter/jumpstarter/client/flasher.py for parameter-related warnings).

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.cursor/rules/driver-compatibility.mdc around lines 45 - 46, The rule in
driver-compatibility.mdc requires deprecating a public parameter with a
warn/ignore period for at least one release and documenting removal + migration
notes, so if this PR actually deprecates/removes a public client parameter,
update the implementation to emit a runtime deprecation warning (use
warnings.warn(...) where the parameter is accepted, following the pattern in
python/packages/jumpstarter/jumpstarter/client/flasher.py), keep the old
parameter behavior intact for one release, and add explicit release notes
describing the removal and migration path before actually removing the parameter
in a later release.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In @.cursor/rules/driver-compatibility.mdc:
- Around line 45-46: The rule in driver-compatibility.mdc requires deprecating a
public parameter with a warn/ignore period for at least one release and
documenting removal + migration notes, so if this PR actually deprecates/removes
a public client parameter, update the implementation to emit a runtime
deprecation warning (use warnings.warn(...) where the parameter is accepted,
following the pattern in
python/packages/jumpstarter/jumpstarter/client/flasher.py), keep the old
parameter behavior intact for one release, and add explicit release notes
describing the removal and migration path before actually removing the parameter
in a later release.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ad7124e2-d7ba-4cb3-a651-9a620fa727f1

📥 Commits

Reviewing files that changed from the base of the PR and between 6f18382 and 5f8a339.

📒 Files selected for processing (3)

• .claude/rules/driver-compatibility.md
• .cursor/rules/driver-compatibility.mdc
• CLAUDE.md

[kirkbrauer]

Added some notes

[kirkbrauer]

I thought we defined a specific upgrade path here, not that both could be outdated?