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:
1. Create your library as a project
.> project.create-empty libraryName
libraryName/main> merge .libraryName.main
These commands create a project for your library without downloading the
basestandard 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.0as 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
latestthat forked the latest released version of your library. With projects, you do not need to create and continually update a branch to represent the
latestreleased 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 /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.Zconvention, 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 thelowest 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! 🎉