DFDS Content Type Migration workflows

The short version

• First time setup only

  • add the package to your solution yarn add -D dfds-contentful-management-tools, yarn install
  • Make sure you have the environment variables set up
    • CONTENTFUL_SPACE_ID (your Contentful space ID)
    • CONTENTFUL_MANAGEMENT_ACCESS_TOKEN (ask for the secret token in the team).

• yarn migrate-auto --environment-id=<envId>--id=<typeId> Downloads the json from type typeId and creates corresponding migration scripts. 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 feature will automatically migrate to Staging. Everybody wins.

• 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. https://github.com/contentful/migration-cli#reference-documentation

• 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.

• yarn migrate-apply --environment-id=<envId> Applies remaining migrations on a Contentful environment. Note: A singleton entry of type migrationLog is used to kept track how far along this environment is with respect to migrations. If the environment doesn't contain a migrationLog, one will be created from scratch. Note: This script should be part of your CI pipeline

The long version

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

1. Developers work on the Dev space, 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 Production spaces. 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, PROD 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: https://github.com/contentful/migration-cli#reference-documentation. Rename field example (change field Id and then field name):

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

At the end, what should be checked into source control is 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 space, the following script is used. This is currently part of the release process, but might be useful for testing purposes: The yarn migrate:apply --space-id=<spaceId> --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 |