Release planning: v2.0 for zero-copy frame API migration

[coderabbitai]

Purpose
Plan the major release (v2.0) to carry the breaking change for a Bytes-based Frame type and zero-copy decoding.

Context and backlinks

• Requested by @leynos
• PR: Optimize frame processor to reduce memory allocations #283
• Comment: Optimize frame processor to reduce memory allocations #283 (comment)

Expected outcomes

• Versioning and release strategy for the breaking change.
• Communication plan and a migration guide outline for downstream users.
• Timeline and coordination checklist, including benchmarking and validation gates.

Acceptance criteria

• Release plan documented and linked from the epic.
• Owners and tentative timeline agreed.

[leynos]

@coderabbitai looking at the codebase, is this issue still relevant? If the issue has been fixed in the code, does the documentation reflect this?

If it is still relevant, please provide an assessment of the issue criticality (critical, high, medium or low), based on risk of the issue impacting the user and the anticipated blast radius.\n\nOnce a decision has been made, apply the appropriate label.

If the issue is documentation ONLY (i.e., no code changes needed), apply the documentation label in addition to the appropriate criticality label.

Please also provide an impact of the required changes.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Fetch issue `#288` details
gh issue view 288 --json title,body,state,labels,comments --jq '{title: .title, body: .body, state: .state, labels: .labels, comments: .comments}'

Length of output: 1768

---

🏁 Script executed:

#!/bin/bash
# Check PR `#283` details and status
gh pr view 283 --json title,state,merged,mergedAt,body,labels --jq '{title: .title, state: .state, merged: .merged, mergedAt: .mergedAt, body: .body, labels: .labels}'

Length of output: 667

---

🏁 Script executed:

#!/bin/bash
# Check PR `#283` details and status with correct fields
gh pr view 283 --json title,state,mergedAt,mergedBy,body,labels,isDraft --jq '{title: .title, state: .state, mergedAt: .mergedAt, mergedBy: .mergedBy, body: .body, labels: .labels, isDraft: .isDraft}'

Length of output: 4041

---

🏁 Script executed:

#!/bin/bash
# Search for Frame type definition
echo "=== Frame type definition ==="
rg -n "type Frame\s*=" --type rust

echo -e "\n=== Frame struct definition ==="
rg -n "struct Frame" --type rust -A 5

echo -e "\n=== Check if docs/efficiency-report.md exists ==="
fd -t f "efficiency-report.md"

echo -e "\n=== Search for v2.0 or release planning docs ==="
fd -t f -e md | xargs rg -l "v2\.0|version 2|zero-copy" 2>/dev/null || echo "No matches found"

Length of output: 3977

---

🏁 Script executed:

#!/bin/bash
# Read the zero-copy execution plan
echo "=== Zero-copy execution plan ==="
cat docs/execplans/9-1-3-enable-zero-copy-payload-extraction-for-codecs.md

echo -e "\n\n=== Roadmap ==="
cat docs/roadmap.md

echo -e "\n\n=== Check for any v2.0 planning docs ==="
fd -t f -e md | xargs rg -n "v2\.0|version 2\.0|major release" -C 2

Length of output: 45652

---

🏁 Script executed:

#!/bin/bash
# Search for any existing v2.0 planning or related issues
echo "=== Search for v2.0 related issues ==="
gh issue list --search "v2.0 OR version 2 OR breaking change OR Bytes" --state all --json number,title,state --limit 20

echo -e "\n=== Check if efficiency report was supposed to be created ==="
rg -n "efficiency.report|efficiency-report" --type md

echo -e "\n=== Search for any TODOs or FIXMEs about Frame type changes ==="
rg -n "TODO|FIXME" --type rust | rg -i "frame|bytes|vec"

Length of output: 2025

---

@leynos, I've completed my analysis of issue #288. Here's my assessment:

Relevance Status: STILL RELEVANT ✅

The issue remains relevant. While ExecPlan 9.1.3 (completed 2026-01-19) implemented zero-copy capabilities at the codec layer via the frame_payload_bytes method, the breaking API change to adopt Bytes as the Frame type has not been implemented. More importantly, none of the planning deliverables specified in this issue have been created:

• ❌ No versioning and release strategy documented
• ❌ No communication plan exists
• ❌ No migration guide (even in outline form)
• ❌ No timeline or coordination checklist
• ❌ The efficiency report mentioned in PR #283 was never created

Documentation Status: NOT ADDRESSED 📋

The codebase still uses Vec<u8> as the Frame type in most places (tests and examples), and no planning documentation exists for the v2.0 breaking change.

Criticality Assessment: LOW 🔵

Risk to users: Minimal current impact

• This is strategic planning work with no immediate user-facing consequences
• No users are currently blocked or affected
• The actual implementation (Epic #284) hasn't begun

Anticipated blast radius: HIGH (when implemented)

• Breaking API change affecting all Frame type usage
• Requires downstream migration
• However, this is a planned and controlled breaking change, reducing the urgency

Rationale for LOW criticality: This is important long-term work, but it's preparatory planning for a future release. The low urgency reflects that users aren't currently impacted, and the planning process itself carries minimal risk.

Issue Classification: DOCUMENTATION ONLY 📝

This issue requires creating planning documentation, not code changes. Therefore, both documentation and low labels are appropriate.

Impact of Required Changes

Deliverables needed:

1. Release strategy document - versioning approach, compatibility commitments, deprecation timeline
2. Communication plan - announcement channels, timing, audience segmentation
3. Migration guide outline - breaking changes inventory, code transformation patterns, testing recommendations
4. Coordination checklist - benchmarking gates, validation criteria, release approval workflow, backlink to Epic #284

Estimated effort: Medium (documentation and coordination planning)

---

🏁 Script executed:

#!/bin/bash
# Apply appropriate labels to issue `#288`
gh issue edit 288 --add-label "documentation,low"

# Verify labels were applied
echo -e "\n=== Verification: Current labels on issue `#288` ==="
gh issue view 288 --json labels --jq '.labels[].name'

Length of output: 116

---

✅ Labels applied successfully

The documentation and low labels have been added to issue #288.

---

Summary

Issue #288 is still relevant and represents important preparatory work for the v2.0 release. The code changes mentioned (Bytes-based Frame type) have not been implemented, and more critically, none of the planning deliverables exist yet.

The LOW criticality rating reflects that this is strategic planning work without immediate user impact, though the eventual implementation will have a high blast radius as a breaking change. The documentation label is appropriate because all acceptance criteria involve creating planning documents rather than code changes.

Next steps for this issue:

1. Create release strategy document with versioning approach
2. Draft communication plan for downstream users
3. Outline migration guide with breaking change inventory
4. Establish coordination checklist with benchmarking gates
5. Link all planning documents to Epic #284

This foundational planning work should be completed before Epic #284 (the actual implementation) begins, ensuring a smooth and well-coordinated major release.