npm package: @kdichev/migration
Description: migration scripts
Author: Aleks Dubinskiy
Latest version: 1.12.0


# 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. 
1. 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_*
1. _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. 
   1. 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. 
1. _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_

 <hr>

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