apache / apache/seatunnel

[Feature][CI&CD] Extend upgrade compatibility coverage beyond the initial cross-version restore workflow

Open
#11,356 2 comments 0 reactions 0 assignees View on GitHub
CI&CD design e2e feature help wanted
Dominant language
Java
Stars
9.7k
Forks
2.4k
Avg merge
3d 9h
Merged PRs (30d)
204

Description

## Background
Issue #11239 and PR #11301 add an important first step for upgrade compatibility: a cross-version restore workflow with representative scenarios.

That work is worth landing, but it should be treated as **phase 1**, not as the full upgrade-compatibility story.

SeaTunnel still needs a clearer release-grade answer to this question:

**What upgrade guarantees do we actually verify before shipping changes that affect persisted runtime state?**

## Problem to solve
An initial restore workflow is useful, but it does not yet cover the broader compatibility problem.

Remaining gaps include:
- scenario coverage is still intentionally small
- not all high-risk state surfaces are represented
- not every risky code area has a clear policy for when upgrade checks should run
- failure output still needs to be actionable for maintainers
- the community still lacks a written compatibility boundary for what is guaranteed and what is best effort

## Proposed scope
Track phase-2 work that turns upgrade compatibility from a single workflow into a maintainable compatibility program.

Suggested scope:
- define the minimum supported upgrade scenarios that must stay green on `dev`
- expand scenario coverage for stateful source, sink, CDC, and checkpoint/restore paths where it materially reduces regression risk
- define when the workflow runs: scheduled only, manually triggered, or selectively required for high-risk changes
- make failures clearly identify whether the break happened during state creation, restore, resume, or post-restore validation
- document the compatibility contract that the workflow is asserting

## Why this needs STIP first
This is not just a CI scripting task. It affects:
- release policy
- CI cost and runtime budget
- which modules/changes are treated as compatibility-sensitive
- what level of backward compatibility SeaTunnel is publicly willing to claim

Because of that, **the claimant should submit a STIP design first and get maintainer agreement before starting implementation**.

The STIP should explicitly define:
- the supported version matrix and scenario-selection strategy
- the minimum high-risk paths that must be covered
- trigger/gating policy for `dev` and for PRs touching risky areas
- artifact/version sourcing and reproducibility rules
- how compatibility failures are triaged and who owns follow-up

## Acceptance criteria
- SeaTunnel has a documented upgrade-compatibility policy instead of only an ad hoc workflow.
- Phase-2 coverage extends beyond the initial scenarios from #11239 / PR #11301.
- Failure output is actionable enough for maintainers to identify the broken stage quickly.
- English and Chinese docs are updated where compatibility guarantees are user-visible.

## Non-goals for the first version
- exhaustive coverage of every connector and every historical version
- turning every PR into a full compatibility matrix run immediately
- claiming stronger guarantees than the workflow actually verifies

## Related work
- Issue #11239
- PR #11301
- Issue #11353
- Issue #11354

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading issue #11239, PR #11301, and related issues #11353 and #11354 to understand the existing restore workflow and open gaps. Prepare the required STIP covering the version matrix, scenarios, triggers, artifacts, reproducibility, and failure ownership before implementation. Done means maintainers agree on the design and the resulting policy, coverage, actionable failures, and English and Chinese documentation meet the acceptance criteria.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions
Domain
ci-cd, documentation, release
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.