Skip to content

Breaking Changes

In general, the AI Module supports upgrading between releases with Update Hooks. Though, there can be breaking changes that are not supported by update hooks that much be communicated as such. This outlines how the AI module highlights these through the release cycle and through change records.

Process

When there is a change that is not supported by an upgrade hook...

  1. Tag the related issue with the Breaking Change (BC) tag.
  2. Append (Breaking Change) to the issue title so that it's easily caught within the release notes. For example: > "Add AI Banana module (Breaking Change)"

  3. In the issue description, ensure there are steps documented for users to handle the breaking change. For example:

    <h3>Breaking Change</h3> <p>There is a new dependency on the AI Banana module.</p> <h3>Upgrade Path</h3> <p>Make sure you re-run <code>composer update drupal/ai -W</code> to ensure the dependency tree resolves correctly.</p>

  4. In order to adhere to Semantic Versioning, it will require a new major version, as to somewhat align with how Drupal core handles its breaking changes.

  5. When generating the release notes, if there are any issues marked as (Breaking Change) copy the Upgrade Path instructions directly into the release notes:

    Upgrade Path

    #123456 Add AI Banana module

    • Breaking Change: There is now new dependency on the AI Pirate module
    • Upgrade Path: Make sure you re-run composer update drupal/ai -W to ensure the dependency tree resolves correctly.

  6. Proceed with the major release process as usual

  7. Create a new Change Record documenting the breaking change...
    • Title: The issue name
    • Published: Enabled
    • Introduced in branch: The active branch that the tag is built from
    • Introduced in version: The new version that is being published
    • Issue links: Link to the relevant issue
    • Description: Include both the Upgrade Path instructions you had built prior

See Also