Skip to content

Commit f46a6b1

Browse files
aman19Kaman19K
committed
docs: add migration guide from v1 to v2
1 parent c9beb80 commit f46a6b1

2 files changed

Lines changed: 253 additions & 0 deletions

File tree

‎MIGRATION_GUIDE.md‎

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
# Contentstack CLI Migration Guide: 1.x to 2.x.x-beta
2+
3+
## Overview
4+
5+
This guide helps you migrate from Contentstack CLI 1.x to the new 2.x.x-beta version. The new version introduces significant improvements in performance, user experience, and functionality.
6+
7+
## Major Changes
8+
9+
### 1. 🚀 TypeScript Module Support (Default)
10+
11+
**What Changed:**
12+
- Removed `export-info.json` support
13+
- TypeScript modules are now the default for export & import operations
14+
- Improved performance and reliability
15+
16+
**Before (1.x):**
17+
```bash
18+
csdx cm:stacks:export -d "./export-data" -k bltxxxxxx
19+
```
20+
The CLI generated an export-info.json file containing a contentVersion field:
21+
contentVersion: 2 for TypeScript modules
22+
contentVersion: 1 for JavaScript modules (default)
23+
This version indicator helped the import process select the appropriate module structure, as TypeScript and JavaScript modules have different structures for assets, entries, and other components.
24+
25+
**After (2.x.x-beta):**
26+
```bash
27+
csdx cm:stacks:export -d "./export-data" -k bltxxxxxx
28+
```
29+
No export-info.json file is generated
30+
TypeScript modules are used by default for all operations
31+
Simplified export structure with consistent module formatting
32+
33+
**Migration Action:** Remove `export-info.json` file generation logic from export plugin.
34+
35+
### 2. 🌿 Main Branch Export (Default)
36+
37+
**What Changed:**
38+
- By default, only the main branch content is exported
39+
- Consistent behavior with import operations
40+
- Faster exports for most use cases
41+
42+
**Before (1.x):**
43+
- Exported all branches by default
44+
45+
**After (2.x.x-beta):**
46+
- Exports main branch by default
47+
- Specify `--branch` for specific branch export
48+
49+
**Examples:**
50+
51+
```bash
52+
# Export main branch (default behavior)
53+
csdx cm:stacks:export -d "./export-data" -k bltxxxxxx
54+
55+
# Export specific branch
56+
csdx cm:stacks:export --branch feature-branch -d "./export-data" -k bltxxxxxx
57+
58+
# Export using branch alias
59+
csdx cm:stacks:export --branch-alias production -d "./export-data" -k bltxxxxxx
60+
```
61+
62+
**Migration Action:** If you need to export specific branches, add the `--branch` flag to your commands.
63+
64+
### 3. 📊 Progress Manager UI (Default)
65+
66+
**What Changed:**
67+
- Visual Progress Manager is now the default UI for export, import, clone & seed operations
68+
- Enhanced user experience with real-time progress tracking
69+
- Console logs are available as an optional mode
70+
71+
## New Progress Manager Interface
72+
73+
### Default Mode: Visual Progress Manager
74+
75+
When you run export/import commands, you'll see a beautiful progress interface:
76+
77+
```
78+
STACK:
79+
├─ Settings |████████████████████████████████████████| 100% | 1/1 | ✓ Complete (1/1)
80+
├─ Locale |████████████████████████████████████████| 100% | 1/1 | ✓ Complete (1/1)
81+
82+
LOCALES:
83+
└─ Locales |████████████████████████████████████████| 100% | 2/2 | ✓ Complete (2/2)
84+
85+
CONTENT TYPES:
86+
└─ Content types |████████████████████████████████████████| 100% | 6/6 | ✓ Complete (6/6)
87+
88+
ENTRIES:
89+
├─ Entries |████████████████████████████████████████| 100% | 12/12 | ✓ Complete (12/12)
90+
```
91+
92+
### Optional Mode: Console Logs
93+
94+
For debugging or detailed logging, switch to console log mode:
95+
96+
**Enable Console Logs:**
97+
```bash
98+
csdx config:set:log --show-console-logs
99+
```
100+
101+
**Disable Console Logs (back to Progress Manager):**
102+
```bash
103+
csdx config:set:log --no-show-console-logs
104+
```
105+
106+
**Console Log Output Example:**
107+
```
108+
[2025-08-22 16:12:23] INFO: Exporting content from branch main
109+
[2025-08-22 16:12:23] INFO: Started to export content, version is 2
110+
[2025-08-22 16:12:23] INFO: Exporting module: stack
111+
[2025-08-22 16:12:24] INFO: Exporting stack settings
112+
[2025-08-22 16:12:25] SUCCESS: Exported stack settings successfully!
113+
```
114+
115+
## Command Changes
116+
117+
### Export Commands
118+
119+
**Basic Export:**
120+
```bash
121+
# 1.x
122+
csdx cm:stacks:export -d "./export-data" -k bltxxxxxx
123+
124+
# 2.x.x-beta
125+
csdx cm:stacks:export -d "./export-data" -k bltxxxxxx
126+
```
127+
128+
**Branch-specific Export:**
129+
```bash
130+
# 1.x (exported all branches)
131+
csdx cm:stacks:export -d "./export-data" -k bltxxxxxx
132+
133+
# 2.x.x-beta (export specific branch)
134+
csdx cm:stacks:export --branch my-branch -d "./export-data" -k bltxxxxxx
135+
```
136+
137+
### Import Commands
138+
139+
**Basic Import:**
140+
```bash
141+
# 1.x
142+
csdx cm:stacks:import -d "./export-data" -k bltxxxxxx
143+
144+
# 2.x.x-beta
145+
csdx cm:stacks:import -d "./export-data" -k bltxxxxxx
146+
```
147+
148+
## Configuration Options
149+
150+
### Progress Manager Configuration
151+
152+
The Progress Manager is enabled by default. You can toggle between modes:
153+
154+
**Available Options:**
155+
- `--show-console-logs`: Display console logs mode
156+
- `--no-show-console-logs`: Display Progress Manager mode (default)
157+
158+
**Global Configuration:**
159+
```bash
160+
# Set default to console logs
161+
csdx config:set:log --show-console-logs
162+
163+
# Set default to progress manager (default)
164+
csdx config:set:log --no-show-console-logs
165+
```
166+
167+
## Migration Checklist
168+
169+
### ✅ Pre-Migration Steps
170+
171+
1. **Backup your current scripts and configurations**
172+
2. **Test the new CLI in a development environment**
173+
3. **Update your CI/CD pipelines**
174+
175+
### ✅ Configuration Updates
176+
177+
- [ ] Decide on default progress display mode (Progress Manager vs Console Logs)
178+
- [ ] Configure global log settings if needed
179+
- [ ] Update documentation and team guidelines
180+
181+
### ✅ Testing
182+
183+
- [ ] Test export operations with main branch (default behavior)
184+
- [ ] Test export operations with specific branches
185+
- [ ] Test import operations with new progress interface
186+
- [ ] Verify clone and seed operations work correctly
187+
- [ ] Test console log mode for debugging scenarios
188+
189+
## Troubleshooting
190+
191+
### Common Issues
192+
193+
**1. Command not found errors:**
194+
- Ensure you've installed the 2.x.x-beta version
195+
- Clear npm cache: `npm cache clean --force`
196+
197+
**2. Missing branch content:**
198+
- Check if you need to specify `--branch` flag for non-main branches
199+
- Verify branch exists in your stack
200+
201+
**3. Progress display issues:**
202+
- Try switching between console logs and progress manager modes
203+
- Check terminal compatibility for progress bars
204+
205+
**4. Performance differences:**
206+
- 2.x.x-beta should be faster due to TypeScript modules
207+
- If experiencing issues, switch to console log mode for debugging
208+
209+
### Getting Help
210+
211+
**Documentation:**
212+
- [CLI Documentation](https://www.contentstack.com/docs/developers/cli)
213+
- [API Reference](https://www.contentstack.com/docs/developers/apis)
214+
215+
**Support:**
216+
- [GitHub Issues](https://github.com/contentstack/cli/issues)
217+
218+
## Benefits of 2.x.x-beta
219+
220+
### 🚀 **Performance Improvements**
221+
- Faster export/import operations with TypeScript modules
222+
- Optimized branch handling
223+
- Reduced memory usage
224+
225+
### 🎯 **Better User Experience**
226+
- Visual Progress Manager with real-time updates
227+
- Cleaner command syntax
228+
- More intuitive default behaviors
229+
230+
### 🔧 **Enhanced Reliability**
231+
- Improved error handling
232+
- Better progress tracking
233+
- More consistent behavior across commands
234+
235+
### 📊 **Better Observability**
236+
- Detailed progress information
237+
- Clear success/failure indicators
238+
- Optional detailed logging for debugging
239+
---
240+
241+
**Need help with migration?** Contact our support team or visit our community forum for assistance.

‎README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,18 @@ npm install -g @contentstack/cli
3232

3333
To verify the installation, run `csdx` in the command window.
3434

35+
## Migration Guide
36+
37+
If you're upgrading from CLI 1.x to 2.x.x-beta, please refer to our comprehensive [Migration Guide](./MIGRATION_GUIDE.md) for:
38+
39+
- **Breaking changes** and new default behaviors
40+
- **Step-by-step migration instructions**
41+
- **New features** like TypeScript module support and Progress Manager UI
42+
- **Command syntax updates** and configuration changes
43+
- **Troubleshooting tips** for common migration issues
44+
45+
📖 **[View Migration Guide →](./MIGRATION_GUIDE.md)**
46+
3547
## Usage
3648
After the successful installation of CLI, use the `--help` parameter to display the help section of the CLI. You can even combine this parameter with a specific command to get the help section of that command.
3749

0 commit comments

Comments
 (0)