# 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](https://git.drupalcode.org/project/flowdrop/-/blob/1.x/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 a 1.0.0 pre-release (alpha or earlier beta)

If you are still on a 1.0.0 alpha or `1.0.0-beta1`, jump to 1.0.0 in one step using the standard procedure above and review the [CHANGELOG](https://git.drupalcode.org/project/flowdrop/-/blob/1.x/CHANGELOG.md) for the breaking changes that landed across the pre-release series. The notable ones for custom code:

- **Typed event classes** replaced `GenericEvent` (since `1.0.0-beta1`). Event subscribers must access typed properties (e.g., `$event->pipeline`) and update type hints.
- **32 internal services** made `public: false` (since `1.0.0-beta1`). Use constructor injection or the public interfaces instead of `\Drupal::service()`.
- **REST API response envelope** changed to `{ success, data, error }` (since `1.0.0-alpha4`).
- **Pagination** moved from `X-Total-Count` header to a `pagination` object in the response body (since `1.0.0-alpha4`).
- **Drupal 10 support dropped** in the 1.0.0-alpha series; minimum is now `^11.2`.
- **Module renaming and service ID changes** during the alpha series — `drush updb` handles entity and config migrations automatically.

## 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).
