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.
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
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