🧭 Synticore Website Compiler - Migration Guide

🎯 Purpose

This page explains how project version upgrades work, how to run them, and what the current migration set changes.

🚦 How Migration Is Triggered

Synticore compares:

• project version (<project>/info.json)
• compiler version (source/resource/info.json)

When project version is older, Synticore can perform in-place migration before continuing tasks.

Version status categories:

• Equal: no migration needed
• Old: migration available and expected
• New: project was built with newer compiler; compatibility risk

🛠️ Migration Tasks You Can Run Manually

Full Upgrade Path

npm run gulp project_update_full

• Runs upgrade from 1.0.0 to current compiler version.

Directed Upgrade Path

npm run gulp project_update_directed

• Interactive range selection (start and end versions).
• Useful for testing or controlled upgrade steps.

🧾 Current Migration Registry State

Current migration registry includes migration to:

• 1.1.0

Migration ID summary in code:

• to: '1.1.0'
• name: Project layout & config schema migration + cache upgrade

🧱 What 1.1.0 Migration Changes

🗂️ Layout And Artifacts

• Removes old package ignore block from project .gitignore if present.
• Moves legacy package.zip to _package/package.zip.
• Moves legacy cache.json into _cache/project/file.json.

🧠 Cache Format Upgrades

• Upgrades project file cache format.
• Upgrades compiler cache format.
• Upgrades image cache format.

✏️ Asset/Path Renames

• in/asset/brand/foreground_wide.png -> in/asset/brand/foreground-wide.png
• Migrates font_icon naming to font-icon across paths/files/references/cache entries.

🔗 Handlebars/Config Token Reference Updates

Migration updates legacy template/config token references, including legacy root assumptions.

🔁 Config Key Moves From Legacy Keys

Migration contains key move steps for legacy config paths, including:

• option.path.ignore_package -> option.package.ignore
• option.path.ignore_nav -> navigation namespace
• option.breadcrumb -> option.navigation.breadcrumb
• option.toc -> option.navigation.toc
• option.url.html_extension -> option.url.clean (converted semantics)
• option.minify.js -> option.js.minify

Notes:

• Some moves are conditional and avoid overwriting existing new-format keys.
• If option.package.ignore or option.package.html.ignore_class is an empty array, migration restores legacy safety values (example / package-ignore).
• For non-empty arrays only, migration preserves legacy values, appends no-package if missing, and deduplicates entries.
• Placeholder token prefixes in content are also rewritten during migration walk.

✅ Recommended Migration Workflow

1. Back up the project directory.
2. Run:

npm run gulp about
npm run gulp project_update_full

3. Verify:

npm run gulp build
npm run gulp package

4. Spot-check:

• config.json for expected key locations
• in/asset/ rename outcomes
• _cache/ regeneration behavior
• task logs in <project>/_log/

🧯 Troubleshooting Migration Issues

🛑 Migration Says No Work Needed

• Check info.json project version.
• Compare with source/resource/info.json compiler version.

❗ Task Fails After Migration

• Run npm run gulp rebuild.
• If still failing, inspect <project>/_log/task_rebuild.log and repo _log/gulpfile.log.

🧩 Template Placeholders Not Resolving

• Confirm migrated config keys exist in current namespace.
• Re-run migration task and check migration logs for token-prefix rewrites.

🧪 Test Fixtures Available In Repository

Historical upgrade fixtures are in:

• source/test/project_upgrade/1.0.0
• source/test/project_upgrade/1.0.1
• source/test/project_upgrade/1.0.2
• source/test/project_upgrade/1.0.3

Use these to validate upgrade behavior across legacy project shapes.