DFDS Content Type Migration workflows

The short version

• First time setup only

  • Run yarn install or npm install on the ops/migration directory
  • Make sure you have the environment variables set up
    • CONTENTFUL_SPACE_ID (mivicpf5zews)
    • CONTENTFUL_ENVIRONMENT_ID (staging, for npm test)
    • CONTENTFUL_MANAGEMENT_ACCESS_TOKEN (ask for the secret token in the team).

• yarn migrate:auto --id=<typename> Downloads the json from type <typename> 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 ops/migration/migrations, and a new or modified file in ops/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=<type> 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:interfaces --id<type> Copies editor interfaces from the 'dev' environment to target environment for a specific type. Not needed the first time a type is auto-migrated.

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 ops/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), the JSON from the new types should be placed in the incomingTypes folder, and the automated diffing tool needs to be run to generate the corresponding migration scripts.
   1. The yarn migrate:auto script (no args required) to take a diff between the incomingTypes and contentTypes folder, and creates a timestamped migration file in the migrations folder. If the auto-creation succeeds, we also replace the file in contentTypes with the file in incomingTypes and delete the latter. In the case where automatic change detection is not possible, you would have to fill in the migration file yourself and delete the corresponding incoming type.
   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=<id> script: creates a file with a timestamped file name and boilerplate content for the type with the specified <id>. 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 ops/migration/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>

Code and folder structure:

| folder | what it does| |--------|-------------| |contentTypes | contains the authoritative version of the content types for this project | |incomingTypes | contains the JSON for the content types that have been changed since last time, and will be used for auto-generating migration scripts when possible | |migrations | contains migration scripts | |services | contains utility functions that are used from tests / production code | |utiltypes | contains utility types used from both tests / services and production code | |test | contains unit and integration tests | |tools | contains test scripts and hacks (not versioned) |

Deployment

tba coming soon...