# Upgrading FlowDrop

This guide covers how to update FlowDrop between versions and what to expect from each upgrade.

## Standard Upgrade Procedure

For any FlowDrop update, follow this sequence:

```bash
# 1. Update the package
composer update drupal/flowdrop --with-dependencies

# 2. Run database updates
drush updb

# 3. Import any config schema changes
drush cim

# 4. Clear the cache
drush cr
```

Always run `drush updb` before `drush cim`. Update hooks may migrate config schemas, and importing config before running them can cause failures.

## Checking for Breaking Changes

Before upgrading, review the [CHANGELOG.md](../../CHANGELOG.md) for the target version. Entries marked **BREAKING** require manual action after updating.

```bash
# Preview database updates without applying them
drush updb --simulate

# Preview config changes before importing
drush cim --preview
```

## Upgrading from 1.0.0-beta2 to 1.0.0

No breaking changes. Standard procedure applies.

## Upgrading from 1.0.0-beta1 to 1.0.0-beta2

### Breaking: Enum return types on trigger and executor interfaces

`FlowDropEventTypeInterface::getCategory()` now returns `EventCategory` enum instead of `string`. `FlowDropEventTypeInterface::getDefaultExecutionMode()` returns `TriggerExecutionMode` enum instead of `string`.

**Action required** if you implemented `FlowDropEventTypeInterface` directly (i.e., you created a custom event type plugin): update your `getCategory()` and `getDefaultExecutionMode()` return types. See [Creating Custom Triggers](../development/custom-triggers.md).

`WorkflowExecutionServiceInterface::execute()` now accepts `WorkflowExecutionMode` enum instead of string constants. `getStatus()` returns `WorkflowExecutionStatus` enum.

**Action required** if you called `WorkflowExecutionServiceInterface` directly: update to pass the enum values.

## Upgrading from 1.0.0-alpha5 to 1.0.0-beta1

### Breaking: Typed event classes replace GenericEvent

All FlowDrop events now dispatch typed event classes instead of `GenericEvent`. If you wrote event subscribers listening to FlowDrop events, update:

- Change property access from `$event->getArgument('key')` to `$event->property`.
- Update type hints in your subscriber methods.

```php
// Before (alpha5)
public function onPipelineComplete(GenericEvent $event): void {
    $pipeline = $event->getArgument('pipeline');
}

// After (beta1)
use Drupal\flowdrop_runtime\Event\PipelineCompleteEvent;

public function onPipelineComplete(PipelineCompleteEvent $event): void {
    $pipeline = $event->pipeline;
}
```

### Breaking: 32 internal services made private

Services marked `@internal` across `flowdrop_interrupt`, `flowdrop_orchestration`, `flowdrop_runtime`, `flowdrop_session`, and `flowdrop_stategraph` are now `public: false`.

**Action required** if you accessed these via `\Drupal::service()` or `$container->get()`: switch to constructor injection or use the provided public interfaces.

## Upgrading from 1.0.0-alpha4 to 1.0.0-alpha5

No action required for most sites. Standard procedure applies.

## Upgrading from 1.0.0-alpha3 to 1.0.0-alpha4

### Breaking: API response envelope changed

All REST API responses now use `{ success, data, error }` envelope. The previous `message`, `code`, and `count` fields have been removed.

**Action required** if you consume the FlowDrop REST API from external code: update your response parsing.

### Breaking: Pagination moved to response body

`WorkflowsController` pagination data moved from HTTP headers (`X-Total-Count`) to a `pagination` object in the response body.

## Upgrading from 0.x to 1.0.0-alpha1

### Drupal 10 support dropped

Minimum requirement is now Drupal `^11.2`. Upgrade Drupal to 11.2 or later before upgrading FlowDrop.

### Module renaming and service ID changes

Several internal modules were renamed and service IDs changed in the 1.0.0-alpha series. Run `drush updb` — update hooks handle the entity and config migrations automatically.

Consult the [CHANGELOG.md](../../CHANGELOG.md) entries for `1.0.0-alpha1` through `1.0.0-alpha5` for the full list of namespace and service ID changes if you have custom code that depends on FlowDrop internals.

## Verifying a Successful Upgrade

After upgrading:

1. Navigate to **Administration > FlowDrop** (`/admin/flowdrop`) and confirm the dashboard loads.
2. Open a workflow in the visual editor and verify nodes and edges render correctly.
3. Execute a simple workflow using the **Synchronous** orchestrator and confirm it completes.
4. Check **Reports > Recent log messages** for any FlowDrop errors (`drush watchdog:show --type=flowdrop`).

## Getting Help

If you encounter an issue not covered here, check the [issue queue](https://www.drupal.org/project/issues/flowdrop) or the [Troubleshooting guide](../guide/troubleshooting.md).
