Skip to content

Commit cdc0b33

Browse files
ryunsong-contentfulryunsong-contentful
authored
[INTEG-3081] Apps Migration Scripts (#10096)
* feat: create migration scripts and readmes * feat: move scripts to a separate directory for organization * cleanup: update scripts and readmes to ensure since they moved to a new directory * feat: improve scripts and readmes * feat: improvements 2 - make sure all reports are saved in a subdirectory * feat: improvements 3 - improve error handling and avoid silently failing * fix: linting validation step in validation script for app migration * fix: pr comments
1 parent f907ac6 commit cdc0b33

File tree

12 files changed

+3385
-0
lines changed

12 files changed

+3385
-0
lines changed

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,5 @@ examples/**/.npmrc
1717
.cursorindexingignore
1818
.specstory
1919
*/example-app
20+
apps-migration-scripts/reports/
21+
apps-migration-scripts/logs/

‎apps-migration-scripts/GETTING_STARTED.md‎

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
# 🚀 Getting Started with App Migration
2+
3+
Your first migration from marketplace-partner-apps to apps repository, step by step.
4+
5+
## 📋 Before You Begin
6+
7+
**Quick checklist** (5 minutes):
8+
9+
- [ ] **Repository structure** - Verify you have:
10+
```
11+
your-projects-folder/
12+
├── apps/ # Target repository
13+
│ └── apps-migration-scripts/ # You are here
14+
└── marketplace-partner-apps/ # Source repository
15+
```
16+
17+
- [ ] **Tools installed** - Quick check:
18+
```bash
19+
node --version # Should be 16+
20+
npm --version # Should be 8+
21+
git --version # Any recent version
22+
jq --version # Any version
23+
```
24+
25+
- [ ] **Repositories updated**:
26+
```bash
27+
# Update both repos to latest
28+
cd ../../marketplace-partner-apps && git pull
29+
cd ../apps && git pull
30+
cd apps-migration-scripts
31+
```
32+
33+
## 🎯 Your First Migration
34+
35+
### Step 1: Choose an App
36+
37+
See what's available:
38+
```bash
39+
./migration-summary.sh
40+
```
41+
42+
Pick an app that's **simple to start with** (avoid complex multi-service apps for your first try).
43+
44+
### Step 2: Preview the Migration (Safe!)
45+
46+
**Always start with a dry-run** - this shows you what will happen without making changes:
47+
48+
```bash
49+
./migrate-app.sh <app-name> --dry-run
50+
```
51+
52+
**Example:**
53+
```bash
54+
./migrate-app.sh amplitude-experiment --dry-run
55+
```
56+
57+
**What to look for:**
58+
- ✅ No error messages
59+
- ✅ Files listed look reasonable
60+
- ✅ Package.json changes make sense
61+
- ✅ TypeScript config adaptations (if applicable)
62+
- ✅ Dependency updates look correct
63+
64+
### Step 3: Run the Migration
65+
66+
If the dry-run looked good:
67+
68+
```bash
69+
./migrate-app.sh <app-name>
70+
```
71+
72+
**This will:**
73+
- Copy all app files
74+
- Adapt package.json for apps repository
75+
- Update dependencies
76+
- Add missing config files
77+
- Fix TypeScript configurations (if needed)
78+
- Add missing test imports (`vi` from `vitest`)
79+
- Run lerna bootstrap
80+
81+
### Step 4: Validate Everything Works
82+
83+
```bash
84+
./validate-migration.sh <app-name>
85+
```
86+
87+
**This tests:**
88+
- File structure is correct
89+
- Package.json is valid
90+
- Dependencies resolve (with security checks)
91+
- App builds successfully
92+
- Tests pass (with 60s timeout protection)
93+
- Linting works (if configured)
94+
95+
**✨ Smart validation features:**
96+
- **Missing files** → Warnings + manual checklist (not failures)
97+
- **Test timeouts** → Graceful handling of watch mode
98+
- **Security issues** → Documented for follow-up (non-blocking)
99+
- **Outdated dependencies** → Listed for manual review
100+
101+
**If validation has issues:**
102+
```bash
103+
# Check the detailed report
104+
cat reports/<app-name>-validation-report-*.md
105+
106+
# For verbose debugging
107+
./validate-migration.sh <app-name> --detailed
108+
```
109+
110+
### Step 5: Manual Testing
111+
112+
Test the migrated app:
113+
114+
```bash
115+
# Navigate to the migrated app
116+
cd ../apps/<app-name>
117+
118+
# Install dependencies (if not done automatically)
119+
npm install
120+
121+
# Try to build
122+
npm run build
123+
124+
# Try to start
125+
npm start
126+
```
127+
128+
**Test checklist:**
129+
- [ ] App builds without errors
130+
- [ ] App starts successfully
131+
- [ ] Basic functionality works
132+
- [ ] No obvious regressions
133+
134+
### Step 6: Test in Contentful
135+
136+
1. Upload the built app to a test Contentful space
137+
2. Test all major features
138+
3. Verify configurations work
139+
4. Check integrations function correctly
140+
141+
### Step 7: Cleanup (Danger Zone!)
142+
143+
**⚠️ Only after you're 100% confident everything works!**
144+
145+
```bash
146+
# Return to migration scripts directory
147+
cd ../apps-migration-scripts
148+
149+
# Preview what will be deleted
150+
./cleanup-migrated-app.sh <app-name> --dry-run
151+
152+
# If you're sure, run the cleanup
153+
./cleanup-migrated-app.sh <app-name>
154+
```
155+
156+
**This will:**
157+
- Create a backup (just in case)
158+
- Remove app from marketplace-partner-apps
159+
- Update configuration files
160+
- Commit the changes
161+
162+
## 🚨 What If Something Goes Wrong?
163+
164+
### Migration Failed
165+
166+
```bash
167+
# Check the logs
168+
cat logs/migration-*.log
169+
170+
# Remove partial migration
171+
rm -rf ../apps/<app-name>
172+
173+
# Try again with verbose logging
174+
./migrate-app.sh <app-name> --verbose
175+
```
176+
177+
### Validation Issues
178+
179+
```bash
180+
# Check the validation report (most important!)
181+
cat reports/<app-name>-validation-report-*.md
182+
183+
# Check manual action items that need your attention
184+
grep "Manual Action" reports/<app-name>-validation-report-*.md
185+
186+
# For detailed debugging
187+
./validate-migration.sh <app-name> --detailed
188+
189+
# Check specific issues in logs
190+
cat logs/<app-name>-validation-*.log
191+
```
192+
193+
**Note:** Modern validation is designed to be helpful, not blocking. Most "issues" are just items for your manual checklist!
194+
195+
### Build Failed
196+
197+
```bash
198+
cd ../apps/<app-name>
199+
200+
# Clear everything and reinstall
201+
rm -rf node_modules package-lock.json
202+
npm install
203+
204+
# Check for TypeScript errors
205+
npm run build
206+
207+
# Check for missing dependencies
208+
npm audit
209+
```
210+
211+
### Need to Rollback After Cleanup
212+
213+
```bash
214+
# Find the backup
215+
ls backups/marketplace-partner-apps-<app-name>-*.tar.gz
216+
217+
# Restore it
218+
cd ../../marketplace-partner-apps/apps
219+
tar -xzf ../../apps/apps-migration-scripts/backups/marketplace-partner-apps-<app-name>-*.tar.gz
220+
cd .. && git add . && git commit -m "Restore <app-name>"
221+
222+
# Remove from apps repo
223+
cd ../apps && rm -rf apps/<app-name>
224+
```
225+
226+
## 💡 Pro Tips
227+
228+
### For Your First Migration
229+
230+
1. **Pick a simple app** - avoid complex multi-service apps
231+
2. **Use dry-run extensively** - it's completely safe
232+
3. **Test thoroughly** - don't rush to cleanup
233+
4. **Read the reports** - they contain valuable info
234+
235+
### Making It Smooth
236+
237+
1. **Check prerequisites first** - saves debugging time
238+
2. **Update repos before starting** - avoids conflicts
239+
3. **One app at a time** - don't try to migrate multiple apps simultaneously
240+
4. **Keep backups** - cleanup creates them automatically
241+
242+
### Getting Comfortable
243+
244+
1. **Run validation twice** - it's fast and catches issues early
245+
2. **Test in a sandbox space** - don't use production for first attempts
246+
3. **Keep notes** - document any custom fixes needed
247+
4. **Ask for help** - use `<script> --help` for quick guidance
248+
249+
## 🎯 What's Next?
250+
251+
After your first successful migration:
252+
253+
1. **Try more complex apps** - multi-service, custom configs, etc.
254+
2. **Batch migrations** - migrate several related apps
255+
3. **Customize the process** - see `TECHNICAL_REFERENCE.md` for advanced options
256+
4. **Share learnings** - help improve the scripts for others
257+
258+
## 📚 More Resources
259+
260+
- **Command reference**: `USAGE_GUIDE.md` - all commands and options
261+
- **Technical details**: `TECHNICAL_REFERENCE.md` - how things work internally
262+
- **Quick help**: `./migration-summary.sh` - commands and available apps
263+
- **Interactive guide**: `./getting-started.sh` - terminal-based tutorial
264+
265+
---
266+
267+
**🎉 You're ready! Start with a simple app and take it step by step.**

‎apps-migration-scripts/README.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# 🚀 App Migration Scripts
2+
3+
Migrate apps from `marketplace-partner-apps` to the `apps` repository with automated scripts, intelligent validation, and comprehensive safety features.
4+
5+
## 🎯 Choose Your Starting Point
6+
7+
### 🆕 **New to Migration?**
8+
```bash
9+
./getting-started.sh
10+
```
11+
Interactive tutorial with app selection, safety checks, and guided first migration.
12+
13+
### 📚 **Want the Complete Guide?**
14+
```bash
15+
cat GETTING_STARTED.md
16+
```
17+
Comprehensive tutorial with examples, troubleshooting, and best practices.
18+
19+
### ⚡ **Quick Reference Needed?**
20+
```bash
21+
./migration-summary.sh
22+
```
23+
See all available apps and get command reminders (auto-exits when done).
24+
25+
### 🔧 **Advanced User?**
26+
```bash
27+
cat USAGE_GUIDE.md
28+
```
29+
Complete command reference, options, and technical details.
30+
31+
## 📋 The Migration Process
32+
33+
```bash
34+
# 1. Preview (always start here!)
35+
./migrate-app.sh <app-name> --dry-run
36+
37+
# 2. Migrate with automatic fixes
38+
./migrate-app.sh <app-name>
39+
40+
# 3. Validate with smart handling
41+
./validate-migration.sh <app-name>
42+
43+
# 4. Test manually in Contentful (essential!)
44+
45+
# 5. Cleanup when fully verified (destructive!)
46+
./cleanup-migrated-app.sh <app-name>
47+
```
48+
49+
✨ **New Features:**
50+
- **Smart validation** - Handles missing files gracefully, adds items to manual checklist instead of failing
51+
- **Timeout protection** - Tests won't hang in watch mode (60s limit)
52+
- **Enhanced error reporting** - Clear, actionable error messages with context
53+
- **TypeScript fixes** - Automatic `vitest/globals` → `node` fixes and `vi` import handling
54+
55+
## 📁 What's In This Directory
56+
57+
| File | Purpose |
58+
|------|---------|
59+
| **Scripts** | |
60+
| `migrate-app.sh` | Main migration script |
61+
| `validate-migration.sh` | Test migration success |
62+
| `cleanup-migrated-app.sh` | Remove from marketplace-partner-apps |
63+
| `getting-started.sh` | Interactive tutorial |
64+
| `migration-summary.sh` | Quick reference tool |
65+
| **Documentation** | |
66+
| `README.md` | This overview (start here) |
67+
| `GETTING_STARTED.md` | Step-by-step tutorial |
68+
| `USAGE_GUIDE.md` | Complete command reference |
69+
| `TECHNICAL_REFERENCE.md` | Advanced technical details |
70+
| **Generated** | |
71+
| `logs/` | All script logs (auto-created, app name prefixed) |
72+
| `reports/` | Migration reports (auto-created, organized by app) |
73+
| `backups/` | Cleanup backups (auto-created for safety) |
74+
75+
## ⚠️ Prerequisites
76+
77+
Ensure you have this structure:
78+
```
79+
your-projects-folder/
80+
├── apps/ # This repository
81+
│ └── apps-migration-scripts/ # You are here
82+
└── marketplace-partner-apps/ # Source repository
83+
```
84+
85+
**Required tools:** Node.js 16+, npm, git, jq
86+
87+
**✅ Auto-setup:** The scripts automatically create `logs/`, `reports/`, and `backups/` directories as needed.
88+
89+
## 🆘 Need Help?
90+
91+
- **Can't decide where to start?** → Run `./getting-started.sh`
92+
- **Script not working?** → Check `GETTING_STARTED.md` troubleshooting section
93+
- **Advanced customization?** → See `TECHNICAL_REFERENCE.md`
94+
- **Command options?** → Use `<script-name> --help` or check `USAGE_GUIDE.md`
95+
96+
---
97+
**🎉 Ready? Most users should start with `./getting-started.sh`**

0 commit comments

Comments
 (0)