📚 Projects library migration cheatsheet

If you're migrating a Unison library from the old namespace-based model to the new project-based model, you'll want to follow these steps.

Why migrate? Your library will be discoverable as a project via the search functionality on Unison Share. PRs and comments will be based on the project model, so projects-based libraries will have better UX support for maintainers. Projects are also evolving to support more advanced dependency management and versioning features, like automatically removing unused code in dependencies, better support for semantic versioning, and UCM commands for staging and preparing releases.

⏱
Migrating your library to a project is quick! These steps should only take 5 minutes.

We'll be assuming your library has something like the following namespace structure:

libraryName
  main
  latest
  releases
    v1_0_0
    v1_1_0
    ...

1. Create your library as a project

scratch/main> project.create-empty libraryName
libraryName/main> merge .libraryName.main

These commands create a project for your library without downloading the base standard library and then merge the contents of your library's main namespace into the project's main branch.

2. Create branches for previous library versions

libraryName/main> branch .libraryName.releases.v1_0_0 /releases/drafts/1.0.0
libraryName/main> branch .libraryName.releases.v1_1_0 /releases/drafts/1.1.0
🧠
Be sure to create the release branch with the namespace as the branch's source and the release draft branch as its destination. Without specifying the source and destination of the branch, your release branch would be created as a child of main. Including the namespace as the source ensures that the new branch is created without establishing a parent-child relationship between the "offshoot" branch and the branch you're currently in.

It's important to respect the three-part semantic versioning scheme for these branches. If your previous namespace is versioned differently, it's ok, just pick version 1.0.0 as an initial release version and increment by one major, minor, or patch version from there as appropriate.

We used to recommend that library authors maintain a namespace called latest that forked the latest released version of your library. With projects, you do not need to create and continually update a branch to represent the latest released version of your namespace. Unison Share will suggest the latest version of your project when users search for it.

3. Push your branches to Unison Share

Push each of the branches of your project to Unison Share.

libraryName/main> push
libraryName/main> push /releases/drafts/1.0.0
libraryName/main> push /releases/drafts/1.1.0

4. Create library releases

Because your branches are formatted with the releases/drafts/X.Y.Z convention, Unison Share will recognize this branch as a potential release. Click on the "Releases" tab for the project on Unison Share and check out the list of "draft" releases at the top. Starting at the lowest versioned release number, click the "Publish" button and confirm the version number on the modal that pops up.

5. Help others discover your project

On the Unison Share project home page, click "Settings" and make sure your library is set to "Public" for all to see! The project home page also has a field in the UI where you can add a quick summary of your library or application. Congrats! Your library is now a project! 🎉

More about projects in Unison

🌟 Full list of common workflows for projects

📚 Projects FAQ's

📚 Codebase organization