From c7b8aa526f4148f3285a1eba88f812c521c5ad6d Mon Sep 17 00:00:00 2001 From: Ivan Kiral Date: Wed, 7 Aug 2024 09:39:06 +0200 Subject: [PATCH] update readme --- README.md | 73 +++++++++++++++++++--------------------------------- package.json | 1 + 2 files changed, 28 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index da5a08c..75756e4 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,27 @@ -# Kontent.ai CLI migrations examples - -The Kontent.ai CLI boilerplate aims to help with your first migration code. We've provided sample migration scripts in the `Migrations` folder. These scripts are written in Javascript and Typescript to show you the basic operations. - -If you are missing your use case, you might find answers in the [Management API reference](https://kontent.ai/learn/reference/management-api-v2). - -The Kontent.ai CLI tool supports only Javascript files, so if you write your migrations in Typescript or any other language you have to transpile your code before running. - -## Installation - -```sh -npm install -``` - -## Setup - -Before you run your migrations, you need to store some information about the environment locally. - -The environment is defined as a named pair of values. For example, "DEV" environment can be defined as a pair of a specific environment ID and Management API key. This named pair of values is stored within your local repository in a configuration file named `.environments.json`. - -```sh -# Adds a 'DEV' environment reference. -kontent environment add --name DEV --environment-id "" --api-key "" -``` - -## Usage - -If you've set up an environment using the method above, you can use the prepared scripts to run all migrations in the `Migrations` directory. - -```sh -# Executes all migration scripts in the 'Migrations' folder to the 'DEV' environment reference within your Kontent project. -npm run migrate:all -``` - -If you want to run a specific migration you can use also script defined in ```packages.json``` - -```sh -# Executes a migration script named 'my_migration'. -npm run migrate "my_migration" -``` - -**Tip**: For more information about Kontent migrations, see the [Kontent.ai CLI documentation](https://github.com/kontent-ai/cli/blob/master/README.md). - -## Feedback & Contribution - -Feedback & Contributions are welcomed. Feel free to take/start an issue & submit PR. +# Kontent.ai migrations examples + +The Kontent.ai migrations boilerplate aims to provide a exemplary introduction in developing migrations using [Kontent.ai data-ops](https://github.com/kontent-ai/data-ops). Migrations allow you to perform any operation supported by the [Management API](https://kontent.ai/learn/reference/management-api-v2) through smaller executable scripts. This repository showcases various migration scenarios, including the creation of different entities. Each migration also includes a rollback function to reverse the changes made by the migration. + + > [!NOTE] + > The migrations in this repository are written in `TypeScript` and must be transpiled before execution. + +## Quickstart + +1. Install required depencies + ```sh + npm ci + ``` +1. Set up mandatory parameters for data-ops migrations: + 1. Copy `exampleParams.json` and rename it to `migrationsParams.json` + 1. Fill in the missing parameters for your environment. + > [!TIP] + > You can have multiple configuration files for different environments. For example, you might have one file for production and another for development. +1. Inspect the migrations in the `src` folder. +1. Examine prepared scripts in `package.json`. +1. Try out the scripts + - e.g. `npm run migrate:all` to run all of the migrations + > [!TIP] + > You can add additional parameters using --. For example, to rollback the next 5 migrations, use `npm run migrate:next -- 5 -b`. + + > [!TIP] + > You can view all parameters by using `npm run data-ops -- migrations -help` \ No newline at end of file diff --git a/package.json b/package.json index 716adf7..7b1dffd 100644 --- a/package.json +++ b/package.json @@ -9,6 +9,7 @@ "migrate:range": "tsc && data-ops migrations run --configFile ./migrationsParams.json --range", "migrate:next": "tsc && data-ops migrations run --configFile ./migrationsParams.json --next", "migrate": "tsc && data-ops migration run --configFile ./migrationsParams.json -n", + "data-ops": "data-ops", "lint": "eslint --fix \"src/*.ts\"", "lint:check": "eslint \"src/*.ts\"", "fmt": "dprint fmt",