rojo/docs/migrating-to-epiphany.md

Rojo underwent a large refactor during most of 2018 to enable a bunch of new features and lay groundwork for lots more in 2019. As such, Rojo 0.5.x projects are not compatible with Rojo 0.4.x projects.

Supporting Both 0.4.x and 0.5.x

Rojo 0.5.x uses a different name for its project format. While 0.4.x used rojo.json, 0.5.x uses roblox-project.json, which allows them to coexist.

If you aren't sure about upgrading or want to upgrade gradually, it's possible to keep both files in the same project without causing problems.

Upgrading Your Project File

Project files in 0.5.x are more explicit and flexible than they were in 0.4.x. Project files can now describe models and plugins in addition to places.

This new project file format also guards against two of the biggest pitfalls when writing a config file:

• Using a service as a partition target directly, which often wiped away extra instances
• Defining two partitions that overlapped, which made Rojo act unpredictably

The biggest change is that the partitions field has been replaced with a new field, tree, that describes the entire hierarchy of your project from the top-down.

A project for 0.4.x that syncs from the src directory into ReplicatedStorage.Source would look like this:

{
    "name": "Rojo 0.4.x Example",
    "partitions": {
        "path": "src",
        "target": "ReplicatedStorage.Source"
    }
}

In 0.5.x, the project format is more explicit:

{
    "name": "Rojo 0.5.x Example",
    "tree": {
        "$className": "DataModel",
        "ReplicatedStorage": {
            "$className": "ReplicatedStorage",
            "Source": {
                "$path": "src"
            }
        }
    }
}

For each object in the tree, we define metadata and children.

Metadata begins with a dollar sign ($), like $className. This is so that children and metadata can coexist without creating too many nested layers.

All other values are considered children, where the key is the instance's name, and the value is an object, repeating the process.

Migrating .model.json Files

No upgrade path yet, stay tuned.

Migrating Unknown Files

If you used Rojo to sync in files as StringValue objects, you'll need to make sure those files end with the txt extension to preserve this in Rojo 0.5.x.

Unknown files are now ignored in Rojo instead of being converted to StringValue objects.