Unison Share is Unison's own code hosting service. Unison's unique code format and tooling enables different strategies for remote repositories. We created Unison Share to support code hosting, library discovery, collaboration, source code viewing, and documentation rendering. This document describes a few common workflows and best practices for hosting your code on Unison Share.
Publish a project to Unison Share
First, You'll want to make sure you're logged in to the Unison Share platform. Run auth.login in the UCM locally.
myProject/main> auth.loginThis will open your default web browser and prompt you to log into Unison Share.
To push your own project to Unison Share, use the push command from inside the project and optionally include the branch you're hoping to publish. This pushes the main branch to @username/myProject/main.
myProject/main> pushFinally, head to the Unison Share url displayed by the UCM to view your hosted project. Enter something for the "Project Description" so users will know at a glance what your library is about! 🥳
It's uncommon in now that Unison supports projects, but if you need to to push a namespace outside of a project, use the push command from inside the namespace you're hoping to share, or use a fully qualified name (one which starts with a dot, .) as the second argument to the command. The destination needs to include your username and the public namespace.
scratch/main> push myUser.public.myCode .myCodeProject visibility and branch permissions
Any project that you create and push to Unison Share after having logged in will show up in your Unison Share workspace at "https://share.unison-lang.org/@yourShareHandle". By default, the projects that you host on Unison Share are private. If you want to enable other users to consume or view your project, be sure to adjust the visibility settings in the Project Settings page.
Currently, Unison Share does not have the concept of "organizations" but projects can still be collaborated on by multiple individuals. Fellow maintainers should clone the project to keep in sync with active development and should create contributor branches instead of pushing directly to the main branch. Your teammates can then submit their PRs to the project via the contributions workflow.
Library structure conventions
For the best experience hosting a library on Unison Share, we recommend creating a project where the main branch represents the latest work in progress, feature branches are used for concurrent workstreams, and release branches or release drafts are snapshots of the main branch at a given point in time.
Note, the main and releases/X.Y.Z branches are special branches that are created for you when you initialize or publish a project, repsectively.
myProject
/main
README
ReleaseNotes
lib
dependencies
/featureBranch
-- branch off of main
/releases/X.Y.Z
/releases/draft/X.Y.Z
-- snapshots of mainRead more the recommended project structure here.
Inside the main branch
Within the main branch of your project, located just under the project root, you should have a lib namespace to contain your library's dependencies. Optionally you can include a README document at the root of your project code. If present, Unison Share will automatically render the README as the landing page of the project.
Another special document you can include at the root of your project is ReleaseNotes, which will be rendered as the release notes for the latest release of your library. This is a good place to include information about how to upgrade from previous versions, or any other details you'd like to convey to users of your library. If Unison Share detects a ReleaseNotes term in your project, it will automatically attach it as the release notes for the latest version of your library.
Release branches
Consumers of your library hoping to obtain the most recent released version of the library would pull @user/project/releases/X.Y.Z, whereas Once a new release is ready, you can hit the "release" button in the Unison Share UI to create a release from main.
The releases/X.Y.Z branch is a special branch that is created by Unison Share which squashes the history of the main branch into a simple snapshot.
Unison Share Catalog and search
The front page of Unison Share is referred to as the Catalog. The catalog is a subset of the public projects hosted on Unison Share, but by no means is it a conclusive list! You can also search for projects by name or by author. The search bar will also look in project descriptions for keywords. In fact, some of the most fun and surprising projects can be found by exploring the public projects of other Unison programmers.
Installing a dependency
Unison Share automatically helps users download the latest release of a library. Clicking the "Use Project" button will open a modal with commands for users to copy. The install command listed in the modal will be auto-populated with the latest release version of the project but you can also browse the project's releases and install a different version.
