Skip to content

Commit 52e770b

Browse files
OMpawar-21OMpawar-21
authored
Merge pull request #2671 from contentstack/v2-dev
version bump
2 parents 8ab1f0f + c56233d commit 52e770b

5 files changed

Lines changed: 1006 additions & 632 deletions

File tree

‎.talismanrc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,6 @@ fileignoreconfig:
33
checksum: 117b66122d3f3043f48724ff9755ec2d4a9dff3c156ceedef753df3014cafee6
44
- filename: packages/contentstack/src/hooks/init/opt-in-plugin-guide.ts
55
checksum: 2b079a93988e2439a03c401f75695fcdbfeb138a75c84707e4bc892536680e9f
6+
- filename: MIGRATION.md
7+
checksum: 1f60cc104771b74b43bf1ed107606d2a54264687a0a5e4b229cda813b829dc45
68
version: '1.0'

‎MIGRATION.md‎

Lines changed: 375 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -228,6 +228,381 @@ csdx launch --help
228228

229229
**Migration Action:** If you use any `launch:*` command, install the `@contentstack/cli-launch` plugin before (or immediately after) upgrading to 2.x GA to avoid `command not found` errors. This applies to 2.x beta users as well, since `launch` was bundled during the beta.
230230

231+
### 8. 🔁 Flag Renames on Export / Import / Export-to-CSV
232+
233+
**What Changed:**
234+
Several flags on `cm:stacks:export`, `cm:stacks:import`, and `cm:stacks:export-to-csv` were renamed or removed. Passing the old flag names now causes an **immediate error** — V2 does not silently fall back.
235+
236+
**cm:stacks:export — Removed Flags:**
237+
238+
| V1 Flag | V2 Replacement |
239+
|---|---|
240+
| `--data` | `--data-dir` |
241+
| `--stack-uid` / `-s` | `--stack-api-key` |
242+
| `--management-token-alias` | `--alias` |
243+
| `--auth-token` / `-A` | use `csdx auth:login`, then `--alias` |
244+
| `-m` | `--module` (long form only) |
245+
| `-t` | `--content-types` (long form only) |
246+
| `-B` | `--branch` (long form only) |
247+
248+
**cm:stacks:import — Removed Flags:**
249+
250+
| V1 Flag | V2 Replacement |
251+
|---|---|
252+
| `--data` | `--data-dir` |
253+
| `--stack-uid` / `-s` | `--stack-api-key` |
254+
| `--management-token-alias` | `--alias` |
255+
| `--auth-token` / `-A` | use `csdx auth:login`, then `--alias` |
256+
| `-m` | `--module` (long form only) |
257+
| `-b` | `--backup-dir` (long form only) |
258+
| `-B` | `--branch` (long form only) |
259+
| `--skip-app-recreation` | **Removed — no replacement** |
260+
261+
> ⚠️ `--skip-app-recreation` is gone entirely. Remove it from all import scripts.
262+
263+
**cm:stacks:export-to-csv — Removed Flags:**
264+
265+
| V1 Flag | V2 Replacement |
266+
|---|---|
267+
| `--data` | `--data-dir` |
268+
| `--stack-uid` / `-s` | `--stack-api-key` |
269+
270+
**Before (1.x.x):**
271+
```bash
272+
csdx cm:stacks:export -s blt123 --data ./export -B main
273+
csdx cm:stacks:import -s blt123 --data ./export -b ./backup -B main
274+
```
275+
276+
**After (2.x.x):**
277+
```bash
278+
csdx cm:stacks:export --stack-api-key blt123 --data-dir ./export --branch main
279+
csdx cm:stacks:import --stack-api-key blt123 --data-dir ./export --backup-dir ./backup --branch main
280+
```
281+
282+
**Also note — `--module studio` renamed:**
283+
V1's `--module studio` is now `--module composable-studio`. Using the old value fails immediately:
284+
```bash
285+
# V1
286+
csdx cm:stacks:export --module studio
287+
288+
# V2
289+
csdx cm:stacks:export --module composable-studio
290+
```
291+
292+
**Migration Action:** Update all export and import scripts to use the new flag names above. Search your CI/CD configs for `--data`, `-s`, `-B`, `-b`, `-m`, `-t`, `--auth-token`, `--management-token-alias`, `--skip-app-recreation`, and `--module studio`.
293+
294+
---
295+
296+
### 9. ⚠️ Export Directory Structure Changed (CRITICAL — Silent Data Loss Risk)
297+
298+
**What Changed:**
299+
V2 changes two structural aspects of the export directory that can cause **silent failures** in downstream pipelines and V1 import operations.
300+
301+
#### 9.1 Global Fields: One File Per UID (was one combined file)
302+
303+
V1 wrote all global field schemas into a single file. V2 writes one file per global field UID.
304+
305+
```
306+
# V1 export layout
307+
export/global_fields/globalfields.json ← all schemas in one array
308+
309+
# V2 export layout
310+
export/global_fields/my_header.json ← one file per UID
311+
export/global_fields/my_footer.json
312+
export/global_fields/shared_banner.json
313+
```
314+
315+
#### 9.2 Content Types: Combined `schema.json` Removed
316+
317+
V1 also wrote `content_types/schema.json` containing all content type schemas as an array. V2 removes this file — only individual `content_types/<uid>.json` files are written.
318+
319+
```bash
320+
cat export/content_types/schema.json # this file does not exist in V2 exports
321+
ls export/content_types/*.json # correct: iterate per-UID files
322+
```
323+
324+
#### 9.3 Branches: `branches.json` No Longer Written
325+
326+
V1 wrote a `branches.json` to the export root. V2 does not write this file and raises no error.
327+
328+
**Migration Action:**
329+
- Update any tooling that reads `globalfields.json` or `content_types/schema.json` to iterate per-UID files.
330+
- Remove any pipeline steps that check for or read `branches.json`.
331+
- If you run a V2 export and then import with a **V1 CLI**, content types and global fields will be silently skipped (see section 10).
332+
333+
---
334+
335+
### 10. 🚨 V2 Export Cannot Be Imported with V1 CLI — Silent Skip (CRITICAL)
336+
337+
**What Changed:**
338+
V2's importer (`cm:stacks:import`) reads only per-UID `<uid>.json` files for content types and global fields. It **explicitly ignores** the V1 aggregate files (`schema.json`, `globalfields.json`). There is no error or warning — the import completes "successfully" with zero content types and zero global fields created.
339+
340+
The same silent-skip applies when running `cm:stacks:audit` against a V1 export directory — the audit reads per-UID files only and will report 0 schemas found.
341+
342+
| Module | V1 file (not read by V2) | V2 file (required) |
343+
|---|---|---|
344+
| Content types | `content_types/schema.json` | `content_types/<uid>.json` (one per UID) |
345+
| Global fields | `global_fields/globalfields.json` | `global_fields/<uid>.json` (one per UID) |
346+
347+
**Scenario that breaks silently:**
348+
```bash
349+
# This appears to succeed but imports 0 content types and 0 global fields:
350+
csdx cm:stacks:export --data-dir ./export -k bltV1stack # exported with V1 CLI
351+
csdx cm:stacks:import --data-dir ./export -k bltV2stack # imported with V2 CLI
352+
```
353+
354+
**Resolution:** Always re-export with the V2 CLI before importing with the V2 CLI. If you must work with a V1 export, split `schema.json` and `globalfields.json` into individual per-UID files first.
355+
356+
**Migration Action:** Do not mix V1-exported data with a V2 import run. Add a step in your pipeline to verify exports were produced by the same CLI major version before importing.
357+
358+
---
359+
360+
### 11. 🔗 Command Aliases Removed
361+
362+
**What Changed:**
363+
Several short-form command aliases that worked in V1 no longer exist in V2. Running them produces a `command not found` error.
364+
365+
| Removed Alias (V1) | V2 Replacement |
366+
|---|---|
367+
| `csdx cm:export` | `csdx cm:stacks:export` |
368+
| `csdx cm:import` | `csdx cm:stacks:import` |
369+
| `csdx cm:import-setup` | `csdx cm:stacks:import-setup` |
370+
| `csdx cm:seed` | `csdx cm:stacks:seed` |
371+
| `csdx tokens` | `csdx auth:tokens:list` |
372+
| `csdx audit` | `csdx cm:stacks:audit` |
373+
| `csdx audit:fix` | `csdx cm:stacks:audit:fix` |
374+
375+
> ✅ **Exception:** `csdx cm:migration` is the one V1 alias that **survived** — it still works in V2.
376+
377+
**Before (1.x.x):**
378+
```bash
379+
csdx cm:export -s blt123 -d ./export
380+
csdx audit --report-path ./my-export
381+
```
382+
383+
**After (2.x.x):**
384+
```bash
385+
csdx cm:stacks:export --stack-api-key blt123 --data-dir ./export
386+
csdx cm:stacks:audit --report-path ./my-export
387+
```
388+
389+
**Migration Action:** Search your scripts and CI/CD configs for the removed aliases above and replace them with their full V2 equivalents.
390+
391+
---
392+
393+
### 12. 🧩 `content-type:*` Deprecated Flags Removed
394+
395+
**What Changed:**
396+
All six `content-type:*` commands (`audit`, `compare`, `compare-remote`, `details`, `diagram`, `list`) had their deprecated V1 flags and multiple short chars removed. These flags printed deprecation warnings in V1 but now **fail with an error** in V2.
397+
398+
**Removed across all `content-type:*` commands:**
399+
400+
| Removed | V2 Replacement |
401+
|---|---|
402+
| `--stack` / `-s` | `--stack-api-key` / `-k` |
403+
| `--token-alias` | `--alias` / `-a` |
404+
405+
**Additional short chars removed per command:**
406+
407+
| Command | Removed Short Chars | Long Flag |
408+
|---|---|---|
409+
| `content-type:audit` | `-c` | `--content-type` |
410+
| `content-type:compare` | `-c`, `-l`, `-r` | `--content-type`, `--left`, `--right` |
411+
| `content-type:compare-remote` | `-o`, `-r`, `-c` | `--origin-stack`, `--remote-stack`, `--content-type` |
412+
| `content-type:details` | `-c`, `-p` | `--content-type`, `--path` |
413+
| `content-type:diagram` | `-o`, `-d`, `-t` | `--output`, `--direction`, `--type` |
414+
| `content-type:list` | `-o` | `--order` |
415+
416+
**Before (1.x.x):**
417+
```bash
418+
csdx content-type:audit --stack blt123 --token-alias myalias -c blog
419+
csdx content-type:compare --stack blt123 -c blog -l 1 -r 2
420+
```
421+
422+
**After (2.x.x):**
423+
```bash
424+
csdx content-type:audit --stack-api-key blt123 --alias myalias --content-type blog
425+
csdx content-type:compare --stack-api-key blt123 --content-type blog --left 1 --right 2
426+
```
427+
428+
**Migration Action:** Replace `--stack` with `--stack-api-key`, `--token-alias` with `--alias`, and use long-form flags for all removed short chars.
429+
430+
---
431+
432+
### 13. 🚫 `--api-version` Flag Removed from Bulk Operations
433+
434+
**What Changed:**
435+
The `--api-version` flag has been **removed** from `cm:stacks:bulk-entries` and `cm:stacks:bulk-taxonomies`. V2 hardcodes `api_version: 3.2` for all publish/unpublish calls. Passing `--api-version` now causes an immediate flag error.
436+
437+
**Before (1.x.x):**
438+
```bash
439+
csdx cm:stacks:bulk-entries --operation publish --api-version 3.2 --environments prod --locales en-us -k blt123
440+
csdx cm:stacks:bulk-taxonomies --operation publish --api-version 3 --environments prod -k blt123
441+
```
442+
443+
**After (2.x.x):**
444+
```bash
445+
csdx cm:stacks:bulk-entries --operation publish --environments prod --locales en-us -k blt123
446+
csdx cm:stacks:bulk-taxonomies --operation publish --environments prod -k blt123
447+
```
448+
449+
**Migration Action:** Remove `--api-version` from all bulk-entries and bulk-taxonomies scripts. API version 3.2 is always used.
450+
451+
---
452+
453+
### 14. ✂️ Short Char Removals Across Other Commands
454+
455+
**What Changed:**
456+
V2 resolved short char conflicts across multiple commands by removing ambiguous or deprecated single-letter flags. Long-form flags are unaffected.
457+
458+
| Command | Removed Short Char | Long Flag (still works) |
459+
|---|---|---|
460+
| `cm:stacks:migration` | `-A` | `--authtoken` |
461+
| `cm:stacks:migration` | `-n` | `--filePath` |
462+
| `cm:stacks:migration` | `-B` | `--branch` |
463+
| `migrate:convert` | `-o` | `--output` |
464+
| `migrate:convert` | `-r` | `--rte` |
465+
| `migrate:export` | `-b` | `--branch` |
466+
| `migrate:export` | `-c` | `--config` |
467+
| `migrate:export` | `-o` | `--org` |
468+
| `app:create` | `-n` | `--name` |
469+
470+
**Before (1.x.x):**
471+
```bash
472+
csdx cm:stacks:migration -n ./my-migration.js -A myAuthtoken
473+
csdx app:create -n my-app
474+
```
475+
476+
**After (2.x.x):**
477+
```bash
478+
csdx cm:stacks:migration --filePath ./my-migration.js --authtoken myAuthtoken
479+
csdx app:create --name my-app
480+
```
481+
482+
**Migration Action:** Replace removed short chars with their long-form equivalents in all scripts.
483+
484+
---
485+
486+
### 15. ⚙️ Console Log Config Key Renamed
487+
488+
**What Changed:**
489+
The internal config key that stores the console log preference was renamed from hyphenated to camelCase. Your V1 log preference is **not carried over** to V2 — you must re-apply it after upgrading.
490+
491+
| Config version | Key stored |
492+
|---|---|
493+
| V1 | `log["show-console-logs"]` |
494+
| V2 | `log["showConsoleLogs"]` |
495+
496+
This does not affect the CLI flag name (`--show-console-logs` still works), only the stored config key. If your setup reads the Contentstack CLI config file directly (e.g. in a dotfile or CI bootstrap script), update the key name.
497+
498+
**Migration Action:** After upgrading to V2, re-run your log preference command:
499+
500+
```bash
501+
# If you use console log mode in CI:
502+
csdx config:set:log --show-console-logs
503+
504+
# If you use progress bar mode (default — run this to clear any stale V1 setting):
505+
csdx config:set:log --no-show-console-logs
506+
```
507+
508+
---
509+
510+
### 16. 📦 Bootstrap App Configs Removed (13 Removed, 8 Remain)
511+
512+
**What Changed:**
513+
`cm:bootstrap` no longer recognises 13 app name values that were valid in V1. Passing any of them now throws `CLI_BOOTSTRAP_INVALID_APP_NAME`. Additionally, the flag names themselves changed (see section 8 above).
514+
515+
**Flag renames:**
516+
517+
| V1 Flag | V2 Flag |
518+
|---|---|
519+
| `--appName` / `-a` | `--app-name` |
520+
| `--directory` / `-d` | `--project-dir` |
521+
| `--appType` / `-s` | `--app-type` |
522+
523+
**Removed `--app-name` values (13 total):**
524+
525+
| Removed App Name | Type |
526+
|---|---|
527+
| `reactjs` | Sample app |
528+
| `nextjs` | Sample app |
529+
| `gatsby` | Sample app |
530+
| `angular` | Sample app |
531+
| `reactjs-starter` | Deprecated starter |
532+
| `nextjs-starter` | Deprecated starter |
533+
| `gatsby-starter` | Deprecated starter |
534+
| `angular-starter` | Deprecated starter |
535+
| `nuxt-starter` | Deprecated starter |
536+
| `vue-starter` | Deprecated starter |
537+
| `stencil-starter` | Deprecated starter |
538+
| `nuxt3-starter` | Deprecated starter |
539+
| `nuxtjs-disabled` | Hidden config entry |
540+
541+
**Valid `--app-name` values in V2 (8):**
542+
543+
| App Name | Description |
544+
|---|---|
545+
| `compass-app` | Compass App |
546+
| `kickstart-next` | Kickstart Next.js |
547+
| `kickstart-next-ssr` | Kickstart Next.js SSR |
548+
| `kickstart-next-ssg` | Kickstart Next.js SSG |
549+
| `kickstart-next-graphql` | Kickstart Next.js GraphQL |
550+
| `kickstart-next-middleware` | Kickstart Next.js Middleware |
551+
| `kickstart-nuxt` | Kickstart NuxtJS |
552+
| `kickstart-nuxt-ssr` | Kickstart NuxtJS SSR |
553+
554+
**Before (1.x.x):**
555+
```bash
556+
csdx cm:bootstrap --appName reactjs --directory ./myapp --appType sampleapp
557+
```
558+
559+
**After (2.x.x):**
560+
```bash
561+
csdx cm:bootstrap --app-name compass-app --project-dir ./myapp
562+
```
563+
564+
**Migration Action:** Replace removed `--app-name` values with one of the 8 valid V2 app names. Update `--appName` → `--app-name`, `--directory` → `--project-dir`, `--appType` → `--app-type`.
565+
566+
---
567+
568+
### 17. 🌱 Seed Stack List Is Now Curated (4 Stacks Only)
569+
570+
**What Changed:**
571+
In V1, running `csdx cm:stacks:seed` without `--repo` triggered a live GitHub API search and presented all matching Contentstack repositories. In V2, the list is fixed — only 4 curated repos are shown in the interactive picker.
572+
573+
**V2 curated list:**
574+
1. `contentstack/kickstart-stack-seed` — Kickstart stack seed
575+
2. `contentstack/kickstart-veda-seed` — Kickstart Veda
576+
3. `contentstack/compass-starter-stack` — Compass starter stack
577+
4. `contentstack/stack-starter-app` — Starter app
578+
579+
If you previously relied on the interactive list to discover repos, those repos no longer appear. Any script that passed a repo name not in this list via the interactive prompt will now time out or fail.
580+
581+
**Migration Action:** Use `--repo owner/repo-name` directly if you need a repository that is not in the curated list:
582+
583+
```bash
584+
csdx cm:stacks:seed --repo contentstack/my-custom-seed-repo -k bltXXX
585+
```
586+
587+
---
588+
589+
### 18. 🛑 Ctrl+C Now Exits with Code 130 (Was an Uncaught Exception)
590+
591+
**What Changed:**
592+
In V1, pressing Ctrl+C during an interactive prompt (e.g. environment selection, alias selection) caused an `ExitPromptError` to be thrown. Depending on how your shell or CI pipeline handled unhandled exceptions, this could produce a non-zero exit code or an error stack trace.
593+
594+
In V2, SIGINT is caught and the process exits cleanly with **exit code 130** — the POSIX standard for SIGINT termination. No stack trace is printed.
595+
596+
**Before (1.x.x):**
597+
- Ctrl+C → `ExitPromptError` thrown → unpredictable exit code, possible stack trace in logs
598+
599+
**After (2.x.x):**
600+
- Ctrl+C → clean exit with code 130
601+
602+
**Migration Action:** If your CI pipeline checks the exit code of CLI commands that may be cancelled interactively, update the expected exit code from a non-zero exception code to `130`. If you catch `ExitPromptError` in any wrapper scripts, remove that handler.
603+
604+
---
605+
231606
## Troubleshooting
232607

233608
### Common Issues

0 commit comments

Comments
 (0)