luigidemasi opened a new issue, #46: URL: https://github.com/apache/camel-kit/issues/46
> Imported from [luigidemasi/camel-kit#78](https://github.com/luigidemasi/camel-kit/issues/78), opened by [luigidemasi](https://github.com/luigidemasi) on 2026-05-13. > Closed by [luigidemasi/camel-kit#202](https://github.com/luigidemasi/camel-kit/pull/202), merged on 2026-09-03. --- ## Context The durable `camel-migrate` design package currently centers on `business-requirements.md` and `design-spec.md`. The workflow manifest also declares `migration-analysis`, but it has no durable artifact path. Graph-accelerated runs may produce `.camel-kit/project-snapshot.md`, and the existing graph infrastructure and guides provide partial structural-candidate checks. The remaining gaps are: - compatibility is represented too coarsely, and some guides still assume it by default; - source-retirement findings are incomplete and not normalized across graph and graph-less discovery; - integration size can be mistaken for evidence that an incremental migration is safe; - operators receive no durable deployment, cutover, rollback, and retirement runbook. Static analysis cannot guarantee discovery of undocumented behavior or prove that an unreferenced artifact is dead. This work must expose evidence, uncertainty, and operator decisions instead. ## Work items Delivery order: risk analysis -> source audit -> safe-seam strategy -> runbook. Each item is one separately reviewable signed core commit. Later work must reference earlier finding IDs rather than independently recomputing the same facts. - [ ] **1. Materialize behavioral-assumption and risk analysis** Materialize the existing `migration-analysis` output as `docs/camel-kit/<PIPELINE_ID>/migration-analysis.md`. Each risk entry must include a stable ID, affected flow or interface, behavioral assumption or evidence gap, category, evidence and source, status (`Confirmed`, `Inferred`, or `Unknown`), impact if false, required validation, owner, and disposition. Remove unconditional API-compatibility defaults from active migration guides. Missing or conflicting evidence must remain explicit rather than being treated as compatibility. - [ ] **2. Add a source-retirement candidate audit** Add a normalized source-retirement section to `migration-analysis.md`. Report candidate-unused artifacts, broken references, confirmed entry points/reachable elements, and analysis gaps separately. Each finding must include a stable ID, type, identifier, source path, evidence, confidence, and required human validation. Use graph data only as corroborated acceleration. Produce the same report contract through bounded source scanning when the graph is missing, stale, malformed, or a query fails. Include coverage and parse-failure information so incomplete analysis cannot be reported as "no candidates found." - [ ] **3. Gate incremental migration guidance on a safe traffic seam** Add a durable `Migration Strategy` section to `business-requirements.md`, classified as: - `Incremental candidate` - `Single cutover required` - `Undetermined - evidence needed` Recommend incremental or strangler migration only when a controllable routing or partition seam is confirmed together with old/new ownership, state boundaries, delivery and ordering implications, duplicate/idempotency protections, observability, and rollback signals. Integration size alone is insufficient. - [ ] **4. Generate an operational migration runbook** Create `docs/camel-kit/<PIPELINE_ID>/migration-runbook.md`. The runbook must cover scope and ownership, prerequisites, configuration and data readiness, deployment sequence, cutover entry/actions/exit criteria, operational validation, rollback triggers/actions/verification, data reconciliation, escalation, soak criteria, source-retirement decision, and unresolved operator decisions. Use only validated project and migration data. Unknown environment-specific values, commands, thresholds, endpoints, and credentials must remain explicit placeholders or operator decisions. ## Acceptance criteria - [ ] MuleSoft, BizTalk, and Camel 2.x/3.x migrations use the same artifact and decision contracts. - [ ] The contracts work with a valid graph and with graph-less fallback discovery. - [ ] Standalone and chained migration modes present the completed package before design approval. - [ ] Workflow manifests, pipeline layout, artifact ownership, provenance, and staleness metadata include the new artifacts. - [ ] Regression fixtures cover confirmed, inferred, unknown, and conflicting risk evidence. - [ ] Paired graph/graph-less fixtures produce equivalent classifications where both paths support the construct and disclose coverage differences otherwise. - [ ] Safe, unsafe, and unknown traffic-seam fixtures verify that incremental guidance is conditional. - [ ] A runbook fixture verifies that unresolved production details are not fabricated. - [ ] Existing entry points are protected from false orphan classifications, including scheduled/external Camel consumers, Mule listener flows, and BizTalk orchestrations with receive ports. - [ ] Canonical resources and Bob remain behaviorally aligned across generated targets. - [ ] Focused tests, source checks, and the mandatory full-reactor build pass. ## Non-goals - Detecting every undocumented behavior statically - Proving source and target behavioral equivalence - Proving that every retirement candidate is dead or safe to remove - Whole-language or dynamic production-usage analysis - Automatically deleting or excluding source artifacts - Executing deployment, traffic switching, cutover, rollback, or infrastructure provisioning - Guaranteeing zero downtime, exactly-once delivery, or successful rollback ## Website impact **Required.** Update the public migration workflow and supported-platform documentation to describe the new artifacts, conditional strategy decision, operator handoff, and analysis limitations. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
