Skip to content

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

Starting with 1.0.0-beta1, the Orchestrator plugin system is also 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

Starting with 1.0.0-beta2, the Trigger system and Workflow Executor APIs are also stable:

  • Trigger contracts: TriggerManagerInterface, FlowDropTriggerConfigInterface, FlowDropEventTypeInterface
  • Workflow executor contracts: WorkflowExecutionServiceInterface, WorkflowExecutionMode, WorkflowExecutionStatus

Starting with 1.0.0-rc1, 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. Unintended BC breaks to stable API will be treated as bugs and fixed in a patch release.