Proposal: release version 1.0.0

[matthewfowles]

This is to propose and discuss what a 1.0.0 version should look like and how it should work.

migration content type

Field name	Kentico type	Actual type
id	string	UUID
filename	dateTime	dateTime
name	string	string

• id - should be a UUID
• filename - should be the migration file name
• name - should be the name of the migration

migration files

• Should contain an up and down function in typescript
• Should pass Kentico client to the user
• Kentico client should pass corresponding typescript types
• Should pass a secondary object with element models
• Element models should pass the corresponding typescript types

Setup

the namespace for the project should be: migrate

• Install the package from NPM
• Setup namespace in the bin

Environment variables

Variable	required	description
API_KEY	✓	Kentico API key
PROJECT_ID	✓	Kentico project id
ENVIRONMENT	✓	Kentico environment
MIGRATION_FOLDER	✓	Kentico migration folder
PREVIEW_KEY	✓	Kentico preview key

Commands:

Init migrate init

Initiate the plugin and set up the migration content type on Kentico

Errors

• Should print a message to the user if creating migration content type fails

Flow

1. Connect to Kentico and create migration content-type
   • if content-type already exists error and log message

Run -- migrate run

Runs all existing migrations that do not exist in Kentico or runs a specific migration passed in the arguments.

arguments:

• --id - Pass the id of the migration to run

Errors

• Should print validation messages out to the user
• Should print a message if the individual migration has already been run

Flow

• all migrations
  1. Get all migrations from Kentico
  2. Compare with local migrations
  3. Gather migrations that have not been run
  4. Run each migration (async)
     • If the migration fails log an error message and continues running the next migration.
     • If the migration succeeds create a migration record for it in Kentico
• Individual migration
  1. Check migration has not been run
  2. Run the migration
     • if the migration fails print error messages
     • if the migration succeeds create a migration record in Kentico

Rollback -- migrate rollback

Rollback the last migration created in Kentico or rollback a specific migration passed in arguments

arguments:

• --id - Pass the id of the migration to run
• --force - Force the migration if there is data associated with it

Errors

• Should print a message to the user if the content type is in use and should fail if not forced
• Should print an error and stop if the last migration is not present in the file system

Flow

• no arguments
  1. Get the latest migration
  2. Compare with local migrations and find migration file
     • Fail if migration file not found
  3. Run rollback
     • If the rollback fails log an error message.
     • if the migration has associated content check for --force argument
       • If force continue with rollback
       • if no force error and inform the user
     • If the rollback succeeds delete the migration record on Kentico
• --id specific migration rollback
  1. Get the migration via id
     • if the migration cannot be found log error
  2. Compare with local migrations and find migration file
     • Fail if migration file not found
  3. Run rollback
     • If the rollback fails log an error message.
     • if the migration has associated content check for --force argument
       • If force continue with rollback
       • if no force error and inform the user
     • If the rollback succeeds delete the migration record on Kentico

make -- migrate make [name]

Create new migration file locally

arguments:

• --desc - Pass the description of the model

Errors

• Should print a message to the user if creating migration file fails

Flow

1. generate UUID
2. concatenate name and title
3. create migration file with inserted description if passed

Testing and Release

We should use tooling such as NP

Readme

Should contain a readme with:

• CI badges
• NPM Badges
• description
• setup instructions
• examples
• caveats
• contributors

Unit Tests

• Build functional pieces of code that can be easily tested
• Setup jest with appropriate packages to test
• Should have a coverage threshold of 90%

E2E tests

E2E tests shouldn't be included in version one

Linting

• Should be set up with husky for linting
• Should be up with prettier
• Should be set up with ESLint
• Should be set up with CommitLint
• Should be setup LGTM

Setup CI

• Setup CI to use the above package
• Create a new release on each merge of a PR
• Setup CI to run tests on PR's

The rest is open for discussion on releasing and I will leave this here...

[alexcanessa]

Very nice job @matthewfowles. Here are some thoughts:

Init

The "record" of whether the tool has been initialised or not is simply the presence of the Migration content type. If present, the CLI logs "This project has already been initialised", otherwise, it creates the Migration content type and succeeds.

I'm not clear on what's wrong with this journey.

Run and Rollback

The main concept that I see all around is that each migration could in theory been run at any time, asynchronously.
I'm against this because migrations depend on previous migrations and therefore on a single synchronous timeline: e.g. I can't change elements of a content type if it hasn't been created before.

I know that the problem you came across is when different branches (different sources of truth for what's the migration order) run them separately, but this shouldn't happen (as we discussed offline).
The source of migrations, every time it gets run, should be unique, to guarantee that the migration timeline is consistent.

What I'd like to do is a check against ran migrations and local migrations. If something smelly is found, the CLI complains about it.

Based on this feedback, I would remove the --id option from everywhere, and restore the batchNumber.

Misc

• We can't use typescript in migrations files, as node won't be able to run it without using ts-node runtime which seems overkill. Keen on discussing more as you know how much I love TS 😍.
• On the make you say to concatenate name and title, I presume you want to keep the datestamp?
• Why is filename field of type dateTime in kentico?