# FlowDrop Backward Compatibility Policy

This document defines the backward compatibility (BC) policy for FlowDrop starting with version 1.0.0. FlowDrop follows **pragmatic semantic versioning** (semver), meaning:

- **Patch releases** (1.0.x): Bug fixes only. No BC breaks.
- **Minor releases** (1.x.0): New features, deprecations. No BC breaks to stable API.
- **Major releases** (x.0.0): May contain BC breaks with migration path documented.

## API Classification

Every PHP class and interface in FlowDrop falls into one of two categories, indicated by PHPDoc annotations. Every class **must** carry exactly one of `@api` or `@internal`.

### `@api`

Classes and interfaces marked `@api` are the **stable public API**. They follow strict semver:

- Method signatures will not change in the 1.x release line.
- New optional parameters may be added.
- New methods may be added to classes (but not to interfaces without a deprecation cycle).
- Removal or renaming requires a major version bump with deprecation in the prior minor.

The stable API includes the **FlowDropNodeProcessor plugin system** — the classes that external modules use to create custom node types:

- **Plugin discovery**: `FlowDropNodeProcessor` attribute, `FlowDropNodeProcessorPluginManager`
- **Plugin contracts**: `FlowDropNodeProcessorInterface`, `AbstractFlowDropNodeProcessor`, `NodeExecutorInterface`, `ConfigEditProviderInterface`, `ExecutionContextAwareInterface`, `TriggerNodeProcessorInterface`
- **Parameter system**: `ParameterBag`, `ParameterBagInterface`
- **Data/Output**: `Data`, `DataInterface`, `Output`, `OutputInterface`
- **Validation**: `ValidationResult`, `ValidationError`, `ValidationWarning`
- **Execution context**: `ExecutionContextDTO`
- **Node metadata**: `NodeMetadata`, `NodeMetadataBuilder`, `NodePort`
- **Config editing**: `ConfigEdit`, `DynamicSchemaEndpoint`, `ExternalEditLink`, `ConfigEditApiEndpoints`

The **Orchestrator plugin system** is part of the stable API — the classes that external modules use to create custom workflow execution strategies:

- **Plugin discovery**: `Orchestrator` attribute
- **Plugin contracts**: `OrchestratorPluginInterface`, `OrchestratorPluginBase`, `OrchestratorInterface`
- **Interrupt contracts**: `InterruptExceptionInterface`, `FlowDropInterruptException`

The **Trigger system** and **Workflow Executor** APIs are stable:

- **Trigger contracts**: `TriggerManagerInterface`, `FlowDropTriggerConfigInterface`, `FlowDropEventTypeInterface`
- **Workflow executor contracts**: `WorkflowExecutionServiceInterface`, `WorkflowExecutionMode`, `WorkflowExecutionStatus`

The **StateGraph**, **Interrupt**, and supporting APIs are also stable:

- **StateGraph contracts**: `StateManagerInterface`, `CheckpointerInterface`, `ApprovalGateInterface`, `StateAwareProcessorInterface`, `ReducerInterface`, `IteratorHelperInterface`
- **StateGraph data**: `GraphState`, `StateUpdate`, `Checkpoint`, `ApprovalStatus`
- **StateGraph exceptions**: `MaxIterationsException`, `StateValidationException`, `CheckpointException`, `IteratorExhaustedException`
- **Interrupt contracts**: `InterruptManagerInterface`, `InterruptPersistenceInterface`
- **Interrupt data**: `InterruptState`, `InterruptType`

### `@internal`

Classes marked `@internal` are implementation details with **no BC promise**:

- May change, move, or be removed in any release (including patches) without notice.
- Should not be extended, instantiated, or type-hinted against by external code.
- Typically also marked `final` to prevent extension.

This includes all classes outside the `@api` surface: entity classes and interfaces, controllers, forms, list builders, hook implementations, concrete service implementations, storage classes, DTOs, exception classes, orchestrator plugins, and queue workers.

## REST API Stability

FlowDrop's REST API endpoints are **stable** starting with 1.0.0:

- Existing endpoint paths will not change in the 1.x line.
- Response structure is additive-only: new fields may be added, existing fields will not be removed or renamed.
- HTTP status codes and error response format will remain consistent.
- No URL versioning is used; current paths constitute the v1 contract.

## Configuration Schema

Configuration schemas (`.schema.yml`) follow these rules in 1.x:

- Existing config keys will not be removed or renamed.
- New keys may be added with sensible defaults.
- Schema changes are additive-only.
- Config export/import compatibility is maintained within the 1.x line.

## Entity Type Stability

Entity type IDs and their base field definitions are stable in 1.x:

- Entity type machine names will not change.
- Base fields will not be removed (new fields may be added via update hooks).
- Storage schema changes will always include update hooks.

## Plugin System Stability

Two plugin types are stable in 1.x:

**FlowDropNodeProcessor** — for creating custom node types:

- The `FlowDropNodeProcessor` attribute and `FlowDropNodeProcessorInterface` will remain backward compatible.
- Plugin discovery mechanisms will not change.

**Orchestrator** — for creating custom workflow execution strategies:

- The `Orchestrator` attribute, `OrchestratorPluginInterface`, and `OrchestratorPluginBase` will remain backward compatible.
- The interrupt contracts (`InterruptExceptionInterface`, `FlowDropInterruptException`) will remain backward compatible.
- Concrete orchestrator implementations (e.g., `SynchronousOrchestratorPlugin`) are `@internal` and not covered by BC guarantees.

New plugin types may be added in minor releases but are not covered by BC guarantees until marked `@api`.

## Drupal Version Support

FlowDrop 1.x requires Drupal `^11.2`. Drupal 10 is not supported.

## Reporting BC Breaks

If you believe a release introduced an unintended BC break to stable API, please report it in the [FlowDrop issue queue on Drupal.org](https://www.drupal.org/project/issues/flowdrop). Unintended BC breaks to stable API will be treated as bugs and fixed in a patch release.
