Rename SampleSheetCombinedVCFFile → JointCalledVCF (deprecation)

[davmlaw]

🤖 Written by Claude

Server-side rename context: SACGF/variantgrid_sapath#343.

On the server, SampleSheetCombinedVCFFile has been renamed to JointCalledVCF (the old name described the file it sits next to, not what the model actually is — a joint-called multi-sample VCF). The server keeps the legacy URL/router endpoints (view_combo_vcf_file, api/v1/sample_sheet_combined_vcf_file/) as aliases pointing at the new viewset, so nothing currently breaks on the wire.

The client repo should follow suit and start the deprecation process so callers (notably the TAU pipeline) can migrate at their own pace.

Proposed changes

1. Add new canonical names

   • Dataclass: JointCalledVCF (mirrors the server model name).
   • Client method: create_joint_called_vcf(...) that POSTs to seqauto/api/v1/joint_called_vcf/.

2. Keep old names as deprecated aliases

   • SampleSheetCombinedVCFFile = JointCalledVCF (or a subclass) — emit DeprecationWarning on instantiation.
   • create_sample_sheet_combined_vcf_file(...) — thin wrapper that emits DeprecationWarning (via warnings.warn(..., DeprecationWarning, stacklevel=2)) then delegates to create_joint_called_vcf.
   • This means any pipeline still importing the old names keeps working but starts surfacing warnings in their logs.

3. Do not bump the API URL version

   • The wire format is unchanged; v1→v2 should be reserved for genuine breaking changes (e.g. if we later add explicit subset membership tracking, change error shapes, etc.).
   • Keep using /api/v1/joint_called_vcf/ as the canonical path; the server keeps /api/v1/sample_sheet_combined_vcf_file/ as a route alias.

4. Ship a client version bump

   • Notify TAU once the deprecated-alias version is released.
   • After a couple of client release cycles with the warning in place, remove the aliases.

Why deprecate rather than hard-rename in the client

We control both ends, so a hard rename would technically work — but a soft deprecation costs us almost nothing (a few lines of alias + warning) and removes any coordination burden with TAU. The server alias means there's no hard deadline; the client deprecation is what actually nudges callers to migrate.

[davmlaw]

🤖 Written by Claude

Follow-up: the server-side rename VCFFile → SingleSampleVCF has just landed alongside the JointCalledVCF rename (see SACGF/variantgrid#1555). Same motivation — VCFFile reads as the generic case when it's actually the per-sample (one BAM → one VCF) case; the new name makes the polymorphism with JointCalledVCF explicit.

The server keeps the legacy URL/router endpoints (view_vcf_file, api/v1/vcf_file/) as aliases pointing at the new viewset, so nothing on the wire breaks.

Please extend the scope of this issue to also cover SingleSampleVCF in the client, mirroring the deprecation pattern:

1. Add new canonical names

   • Dataclass: SingleSampleVCF (mirrors the server model name).
   • The existing VCFFile dataclass becomes an alias.

2. Keep VCFFile as a deprecated alias

   • VCFFile = SingleSampleVCF (or a subclass) — emit DeprecationWarning on instantiation.
   • Any client method that historically used VCFFile keeps its signature; new code should reference SingleSampleVCF.

3. Wire path stays on /api/v1/vcf_file/ for now

   • The server has /api/v1/single_sample_vcf/ as the new canonical route and keeps /api/v1/vcf_file/ as the alias, same shape as the joint_called_vcf / sample_sheet_combined_vcf_file pair.
   • Client can switch to the canonical path in the same release that introduces the dataclass rename, since the server accepts both.

4. Same release cadence

   • Bundle both renames (JointCalledVCF + SingleSampleVCF) into one client release with deprecation warnings.
   • Single notification to TAU covers both.