DFDS Content Type Migration workflows

This package facilitates working with Contentful migrations. It can infer migrations from content model changes on a Contentful environment and then apply them to other environments (such as staging or master) as part of your CI release pipeline. This is a wrapper around Contentful Migration API.

Usage

Essential scripts

• yarn migrate-auto --environment-id=<envId> --id=<typeId> Compares the JSON from type typeId on the Contentful environment to the JSON stored in migration/contentTypes and creates corresponding migration script for the difference. This will work for the case when you

  • add a new type
  • add a new field to an existing type
  • Upon success, you should have a new file in migration/migrations, and a new or modified file in migration/contentTypes
  • Commit those 2 files together with your code changes, and your content model changes can then be applied (see migrate-apply) as part of your normal release pipeline.

• yarn migrate-manual --id=<typeId> If the automatic migration is not possible, we use this script to create a dummy migration file which you have to fill in manually, the syntax for migrations is described here.

  Remember to update the local JSON in migration/contentTypes along with the manual migration to reflect the changes to the data model.

• yarn migrate-apply --environment-id=<envId> Applies remaining migrations on a Contentful environment. Note: A singleton entry of type migrationLog is stored in the Contentful environment to keep track of what migrations have already been applied on this environment. If the environment doesn't contain a migrationLog, one will be created from scratch. Note: This script should be part of your CI pipeline

Additional scripts

• yarn migrate-reorder --environment-id=<envId> Tests if any of the migrations in the local setup have been applied out of order (relative to the specified environment) and offers to reorder them.

• yarn migrate-interfaces --id=<typeId> Copies editor interfaces from the 'dev' environment to target environment for a specific type. Not needed the first time a type is auto-migrated.

Installation

Using npm: npm install @dfds-contentful/migration

Using yarn: yarn add @dfds-contentful/migration

Recommended environment variables

• CONTENTFUL_SPACE_ID (your Contentful space ID)
• CONTENTFUL_MANAGEMENT_ACCESS_TOKEN (the CMA token of your contentful space).

The typical workflow with using migrations on Contentful environments

Here is the developer workflow for making changes to Contentful Types:

1. Developers work on the dev environment, changing content types and creating mock content until the feature is ready to be released to the editors.

2. Once the feature / content type is ready, it is the developer's responsibility to make sure the changes propagate forward to staging and master environment. Note that the authoritative version of the content types is in the folder migration/contentTypes

3. If the changes made by the developers are trivial (adding a new type, or adding a new field to an existing type), use migrate-auto

   1. The yarn migrate-auto script takes a diff between the Contentful type typeId (from the environment specified in envId) and the contentTypes folder, and creates a timestamped migration file in the migrations folder. In the case where automatic change detection is not possible, you would have to run yarn migrate-manual fill in the migration file yourself.
   2. In the case of new types, the yarn migrate-auto script also generates migrations for the editor interfaces. Unlike the JSON for the types, the JSON for editor interfaces is not stored together with the code, and will be propagated only once thru staging and master, at which point, master becomes the authoritative truth on editor interfaces.

4. If the changes made by the developer are non-trivial, migration scripts need to be run manually:

   1. The yarn migrate-manual --id=<typeId> script: creates a file with a timestamped file name and boilerplate content for the type typeId. For migration API syntax see This Migration CLI docs.

      Rename field example (change field Id and then field name):

      myType.editField(‘header’).changeFieldId(‘header’, ‘title’).name(‘Title’);

What should be checked into source control:

• The change to the data model in contentTypes and
• The corresponding migration(s) in the folder migrations

In order to apply migrations from the migrations folder to a Contentful environment, the following script is used. This is currently part of the release process, but might be useful for testing purposes:

yarn migrate-apply --space-id=<spaceId> --environment-id=<envId> --management-token=<token>

Folder structure (within the project that's using this package)

| folder | what it does | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | contentTypes | contains the authoritative version of the content types for this project | | incomingTypes | temporary folder containing the JSON for the content types downloaded from Contentful, and is used for diffs against the JSON in contentTypes to generate delta migrations, when possible | | migrations | contains migration scripts to be applied on target environments |