Skip to content

Upgrade and compatibility policy

This page states supported platform versions, beta-to-1.0 upgrade expectations, and API stability commitments for Context Control Center (CCC). It applies to the 1.0.x release line unless a newer major documents otherwise.

For day-to-day API boundaries, see API stability.

Supported platform versions for 1.0

CCC 1.0.x targets:

Component Supported versions
Drupal core 10.5+ or 11.2+ (core_version_requirement in ai_context.info.yml)
PHP Match Drupal core requirements for your core version (PHP 8.1+ on Drupal 10.5; PHP 8.3+ on Drupal 11.2+)
AI ^1.4 or ^2
AI Agents ^1.2 (submodule of AI)
Content Moderation, Taxonomy, Views, Workflows Required core modules (installed with Standard)

Optional integrations

These modules extend CCC but are not required for a minimal install:

Module Supported version When needed
Dynamic Entity Reference ^3.2 Entity Item scope and entity-items field
Diff ^1.0 Revision comparison
Scheduler ^2.3 Scheduled publish/unpublish
Scheduler Content Moderation Integration ^3.0 Scheduled moderation state changes
Document Loader ^2.0.3 Content importers
AI File to Text ^1.0 File extraction for importers
Document Loader Webpage ^1.0 Optional URL importer
Canvas ^1.8.0 Canvas AI integration

Composer require and suggest entries in the project composer.json are the canonical dependency list.

Beta status and release line

CCC is currently in beta on the 1.0.x branch. Tagged beta releases (1.0.0-beta1 through the latest beta) may include schema updates, configuration changes, and API adjustments. Read release notes on drupal.org before upgrading.

After 1.0.0 stable, public APIs documented in API stability follow Drupal contrib deprecation expectations. Internal APIs may change without that guarantee.

Beta-to-1.0 upgrade paths

  1. Take a database backup and export configuration if you rely on config sync.
  2. Update Drupal core, PHP, AI, and AI Agents to supported versions.
  3. Update CCC to the latest 1.0.x tag (or commit) available for your track.
  4. Run database updates:

bash drush updatedb -y drush cr

  1. Review release notes for manual steps, especially when crossing beta3 or later betas.

Skipping intermediate beta releases

Sites may upgrade directly to the latest beta or release candidate if Composer/requirements allow it, but you must still run all pending hook_update_N() functions. Skipping a tagged release in Composer does not skip database updates — drush updatedb applies every update your site has not yet run.

If you jump from an early beta to a later one, expect a longer update chain (updates 10001–10019 and any additions on 1.0.x). Allow maintenance window time for batch updates.

Configuration and content preservation

Upgrades are designed to preserve:

  • Context item entities and field data (including revisions when enabled)
  • Per-agent context configuration (ai_context.agents)
  • Module settings (ai_context.settings and related config)
  • Usage records (when usage tracking is enabled)

Updates may rename, migrate, or split configuration keys (for example moving publishing defaults from bundle config to ai_context.settings in update 10008). Import config sync after running updates on each environment so active config matches the new schema.

Database updates and known upgrade work

CCC ships numbered updates in ai_context.install (ai_context_update_10001 and later). Notable maintenance includes:

  • Scope index and entity schema — early beta updates backfill tables and indexes used for selection. Updates 10004, 10006, and 10011 read stored scope from SQL so they can finish while the old serialized column is still present. Update 10007 writes form and view displays through the Config API so it can finish while those displays still reference the removed ai_context_map formatter. Update 10026 then converts the serialized column to dedicated rows.
  • Publishing and Scheduler settings — migrated off bundle config (10008).
  • Dedicated editorial workflow — context items use the module-owned ai_context_editorial workflow (10013 and related work).
  • Beta3 compatibility repair — updates 10011 and 10014 repair context items left with a NULL revision_id after beta3 failures.
  • Entity scope terminology rename — updates 10015–10019 migrate stored scope values, usage fields, DER field storage, and historical revisions from entity_bundle / target_entity to entity_type / entity_item. Custom code using the old identifiers must be updated during the same deployment; see API stability — Beta upgrade.

If drush updatedb reports failures, note the failing update number and file an issue with steps to reproduce. Do not re-run failed updates manually without maintainer guidance.

Handling upgrade defects

  • Before 1.0 stable: report regressions on drupal.org with the versions you upgraded from and to, update numbers executed, and log excerpts.
  • Data repair issues discovered after a beta release may ship as follow-up updates (as with 10014) rather than new features.
  • Security issues: follow SECURITY.md — use confidential issues, not the public queue.

After 1.0.0

Surface Commitment
Public APIs on API stability Supported; breaking changes follow Drupal deprecation policy
@internal classes and services No compatibility guarantee
Configuration schema Stable within 1.x unless documented in change records
Beta-only behavior Removed or finalized at 1.0.0; see release notes