Issue #3586276: Rename entity bundle and target entity scope plugins for better DX

Tamas Balogrequested to merge
issue/ai_context-3586276:3586276-issue-branch into 1.0.x

Description

Follow-up to #3586148 (closed). The Entity Bundles and Target Entities scopes had near-identical descriptions ("… relevant for this context"), so users could not clearly distinguish the type-level scope from the item-level scope.

This MR renames both scopes, updates their help text using the exact copy from the UX review, and completes the terminology change throughout the public API, configuration, storage, Views integration, and documentation.

Breaking changes (beta)

This MR is a full terminology sweep, not a label-only change. There are no BC wrappers. Custom code, themes, and integrations that reference the old names must be updated when upgrading.

Run drush updatedb after deploying the new code. Update hooks 10015 through 10019 migrate the stored configuration and data for this terminology sweep.

Note: 1.0.x also ships update_10014(), which migrates context items to the module-owned editorial workflow. That hook is unrelated to this rename work and may run on the same upgrade if the site has not applied it yet.

Scope plugins

Old New
Plugin ID entity_bundle (AiContextScopeEntityBundle) entity_type (AiContextScopeEntityType)
Plugin ID target_entity (AiContextScopeTargetEntity) entity_item (AiContextScopeEntityItem)
Config ai_context.scope_settings.entity_bundle ai_context.scope_settings.entity_type
Config ai_context.scope_settings.target_entity ai_context.scope_settings.entity_item
Setting key target_entity_types entity_item_types

update_10015() migrates:

  • Scope-settings configuration
  • Stored scope maps on default and historical context-item revisions
  • The scope index table
  • Agent scope_subscriptions

update_10016() renames the Entity Item scope setting from target_entity_types to entity_item_types.

update_10019() provides an idempotent historical-revision follow-up for sites that ran an earlier version of update_10015().

Cache context

Old New
ai_context.target_entity ai_context.entity_item
AiContextTargetEntityCacheContext AiContextEntityItemCacheContext

Custom render arrays or integrations that list ai_context.target_entity in #cache['contexts'] must use ai_context.entity_item instead.

Public PHP API (AiContextItem)

Old New
getTargetEntities() getEntityItems()
hasTargetEntities() hasEntityItems()
getTargetEntityData() getEntityItemData()
buildTargetEntityRenderArray() buildEntityItemRenderArray()
getTargetEntityMarkup() getEntityItemMarkup()
matchesTargetEntity() matchesEntityItem()

The base field machine name changes from target_entities to entity_items.

When dynamic_entity_reference is installed, update_10018():

  • Installs the new entity_items field storage
  • Copies current and revision data
  • Removes the legacy target_entities storage
  • Migrates form and view display components
  • Migrates diff.plugins configuration

Public PHP API (AiContextUsage)

Old New
getTargetEntityType() / setTargetEntityType() getEntityItemType() / setEntityItemType()
getTargetEntityId() / setTargetEntityId() getEntityItemId() / setEntityItemId()

update_10017() migrates:

  • target_entity_type to entity_item_type
  • target_entity_id to entity_item_id
  • The composite lookup index
  • Stored ai_context_usage Views configuration

Views and UI plugins

Old New
Views field plugin ai_context_target_entity_link (TargetEntityLinkField) ai_context_entity_item_link (EntityItemLinkField)

The shipped views.view.ai_context_usage configuration is updated. Exported site overrides may need to be re-exported or updated after running updb.

Documentation

The developer API-stability documentation includes an old-to-new reference for the renamed plugin IDs, configuration, cache context, fields, Views plugin, and public PHP methods.

Upgrade note

This module is currently in beta. Deploy the new code, run drush updatedb, and rebuild caches before continuing to use the site.

The Dynamic Entity Reference field definition follows the installed storage name while updates run, allowing the earlier update hooks to load context items before update_10018() completes the field-storage migration.

Testing instructions

Automated coverage includes:

  • Scope plugin and configuration renames
  • Scope maps, index rows, agent subscriptions, and revisions
  • Usage field storage and data preservation
  • DER current and revision data preservation
  • Interrupted and repeated DER migration runs
  • Sites without dynamic_entity_reference installed
  • Custom form and view display migration
  • Entity-query compatibility after migration
  • Exact Entity Types and Specific Entities descriptions
  • Scope overview labels and descriptions
  • The visually hidden, accessible Specific Entities picker heading

Relevant Unit, Kernel, and Functional tests pass locally. PHPCS, PHPStan, cspell, ESLint, Stylelint, and Composer lint pass.

Manual testing checklist

  1. Go to /admin/config/ai/context/settings/scope.

    • Confirm the rows read Entity Types and Specific Entities.
    • Confirm Entity Bundles and Target Entities are no longer shown.

  2. Go to /admin/config/ai/context/items/add and open Context Scope.

    • Confirm Entity Types explains that the context applies to every entity of a selected type.
    • Confirm Specific Entities explains that the context applies only to selected items.

  3. Under Specific Entities, inspect the entity picker.

    • Confirm the redundant field heading is not visually displayed.
    • Confirm the picker retains an accessible hidden heading.

  4. Select Manage Entity Types and Manage Specific Entities.

    • Confirm the links open the corresponding settings pages.
    • Confirm their titles are Entity Types Settings and Specific Entities Settings.

  5. Go to /admin/config/ai/context/settings/agents and edit an agent.

    • Confirm Entity Types is available as a subscribable scope.
    • Confirm Specific Entities is not offered as a subscribable scope.
  • I have updated the MR title to use format: Issue #1234: My issue title.
  • I have noted any required post-merge steps (config imports, cache rebuilds, manual changes)
  • I have updated the MR description to include: Closes #1234
  • I have performed a self-review of my own code
  • This MR contains no breaking API or hook changes, or they are explicitly documented in the description
  • I have added or updated tests, or explained in the description why this change is not covered by tests
  • I have updated documentation for any new or changed functionality
  • I have written testing instructions and verified them locally

AI Compliance

Note

  • AI Assisted Code
    Mainly written by a human; AI used for autocomplete or partial generation under full human supervision.
  • AI Generated Code
    Mainly generated by AI, reviewed and approved by a human before this MR was created.
  • Vibe Coded
    Generated by AI and only functionally reviewed before this MR was created.

Closes #3586276

Edited by Kristen Pol

Merge request reports