Migrating between versions

Migrating between versions

Why migrations exist

Each scaffolder version may change templates, add new files, or modify existing standards. The migration system ensures your projects stay current without losing your customizations.

Version stepping

Scaffolder enforces sequential version stepping. You cannot skip major versions — each step must be applied in order. For example:

• v0.4.0 → v0.5.0 → v0.6.0 (correct)
• v0.4.0 → v0.6.0 (blocked — must go through v0.5.0 first)

Minor and patch versions within the same major version can be stepped through automatically.

What changes between versions

Each version transition is defined in src/migrations/. A migration specifies:

• Files added — new files introduced in this version
• Files changed — existing files with updated content
• Files removed — files no longer needed
• Breaking changes — whether this version has incompatible changes
• Instructions — any manual steps required

Running a migration

sc update "project-name"

The update command reads your project’s .scaffolder file to determine the current version, then applies each migration step in sequence.

Handling changed files

For each changed file, you choose:

1. Overwrite — replace with the new template (loses your customizations)
2. Merge — keep your file and manually merge changes
3. Skip — keep your current file unchanged
4. Show diff — view differences before deciding

Backups

Before any migration, a full backup is created at:

.scaffolder-backup/[date]-v[version]/

To restore from a backup:

sc update "project-name" --rollback

Checking version info

View what changed in each version:

cat versions.json

This file maps every version to its changes and breaking status.