Group 3.3 to 4 Migration

Production Group Schema documents what drupal.org actually runs today (Group v3.3). Group v4 Target Design shows the version this initiative is meant to converge toward. This page compares the two directly and lays out what upgrading between them would actually take.

The comparison below is grounded in diffing the two real codebases side by side — ~/Sites/pl-drupalorg (Group 3.3.5, production) and ~/Projects/groups-on-d11 (Group 4.0.x-dev) — not a changelog review.

Latest 4.0 release: 4.0.0-alpha2, published 2026-08-21. Group v4 is not yet stable — only two releases exist (4.0.0-alpha1, 2026-04-24, and 4.0.0-alpha2), no beta or RC yet, and alpha releases are not covered by Drupal security advisories. So this covers what’s confirmed by diffing the two actual codebases, not a guarantee that nothing else changes before 4.0 ships as stable.

What’s already identical

This is a smaller gap than a major-version bump usually implies:

The entity architecture is the same. Both versions already use group_relationship as the entity type ID (id = "group_relationship" in both codebases’ GroupRelationship.php). The group_content → group_relationship table rename that a major version bump might suggest already happened before 3.3 — there is no table rename or data migration needed for this upgrade.
The plugin architecture is the same. Both have identical Plugin/Group/Relation, RelationHandler, and RelationHandlerDefault directory structures. Group did not restructure its relation-handling system between these versions.

What actually changes — one thing, and it’s automatic

The config key on every group_relationship_type entity renames from content_plugin → relation_type (the plugin ID values — group_membership, group_node:documentation, etc. — stay the same; only the property name changes). Group v4 ships its own automatic update hook (group.install) that performs this rename for every relationship type when you run drush updb. This isn’t something to hand-build — it’s Group module’s own upgrade path, verified directly in the 4.0.x-dev source:

// group.install (Group 4.0.x-dev)
// Rename "content_plugin" to "relation_type" on group relationship types.
$plugin_id = $relationship_type->get('content_plugin');
$relationship_type->clear('content_plugin');
$relationship_type->set('relation_type', $plugin_id);

High-level migration plan

Version bump. composer require drupal/group:^4.0, run drush updb on a staging copy. The content_plugin → relation_type rewrite happens automatically across all six relationship types.
Config re-export. drush cex to capture the renamed keys into config/sync, replacing the current content_plugin-keyed YAML.
Custom code audit. Grep the do_group_pin, do_multigroup, do_group_extras, do_group_mission, do_group_language, do_notifications, do_discovery, and do_profile_stats modules for anything reading the content_plugin property or config key directly (method calls, YAML overrides, PHPStan type hints). Since the plugin ID values don’t change, business logic that only cares about the plugin ID is unaffected — only code touching the renamed property/method needs updating.
Dependency audit (not yet verified — open item, not confirmed clean). Any other contrib modules drupal.org runs alongside Group that pin to ^3 need a compatibility check against ^4.
Staging validation. Group creation, membership, and permission checks before promoting to production — even a mechanical rename touches core group functionality site-wide.

Net assessment

Despite the major-version number, this is closer to a module upgrade with an automatic config-key rename than a data migration or re-platform. The architecturally significant work (the group_content → group_relationship rename, the relation-handler plugin system) is already behind both versions. The remaining gap is one config property rename that Group’s own update hook handles, plus the custom-code and dependency audits above.

Why a major version, then?

Group’s own maintainers publish an explicit rationale — meta/roadmap issue #3493574, linked from the 4.0.0-alpha1 release notes (“all of the major BC breaks are in place”). It breaks into four themes:

Raise the platform floor

#3493593 Minimum version set to Drupal 11 (drops D9/D10 support).

Adopt Drupal 11 core APIs instead of contrib workarounds

#3493597 Convert access policies to core’s Access Policy API, dropping the Flexible Permissions dependency.
#3506097 Entity type annotations → PHP 8 Attributes.
#3508876 Hooks → OOP hooks with attributes.

Pay down accumulated tech debt

#3493807 Drop deprecated code.
#3494780 Re-evaluate the Entity API contrib dependency; drop dead code.
#3493741 Drop the VariationCache dev dependency; reset the minimum upgrade path to the latest v3 release.
#3494986 / #3506163 / #3507425 DI review, constructor property promotion, typehints — general PHP 8 modernization.

Real behavioral/API breaks — the actual reason it’s a major, not a minor

#2872697 Stop saving an entity as a side effect of adding/removing it from a group.
#3526265 Disallow automatic membership outside the form approach; remove the wizard workflow entirely.
#3604203 content_plugin → relation_type (already covered above).
A cluster of interface/class renames (GroupPermissionHandlerInterface, GroupViewBuilder, GroupMembershipTrait, and others).

Explicitly postponed to 4.1.x: #3499398 a new non-wizard editor flow.

Net read: a genuine major version — real BC breaks, not just a relabeling — but a D11-floor-and-PHP8-modernization sweep plus two behavioral changes, not a data-model rewrite. Consistent with the codebase diff above: the schema architecture was already stable going into 4.0.