Unison Shareis 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. Runauth.login
in the UCM locally.
myProject/main> auth.login
This will open your default web browser and prompt you to log into Unison Share.
To push your own project to Unison Share, use thepush
command from inside the project and optionally include the branch you're hoping to publish. This pushes themain
branch to @username/myProject/main.
myProject/main> push
Finally, 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 anamespaceoutside of a project, use thepush
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 thepublic
namespace.
.> push myUser.public.myCode .myCode
Project 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 shouldclone
the project to keep in sync with active development and should createcontributor branchesinstead of pushing directly to themain
branch. Your teammates can thensubmit their PRs to the project via the contributions workflow.
Library structure conventions
For the best experience hosting a library on Unison Share, we recommendcreating a projectwhere themain
branch represents the latest work in progress, feature branches are used for concurrent workstreams, and release branches or release drafts are snapshots of themain
branch at a given point in time.
Note, themain
andreleases/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 main
Read more the recommended project structure here.
Inside themain
branch
Within themain
branch of your project, located just under the project root, you should have alib
namespace to contain your library's dependencies. Optionally you can include aREADME
documentat 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 isReleaseNotes
,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 aReleaseNotes
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 frommain
.
Thereleases/X.Y.Z
branch is a special branch that is created by Unison Share which squashes the history of themain
branch into a simple snapshot.
Unison Share Catalog and search
Thefront page of Unison Shareis referred to as the Catalog. The catalog is asubsetof 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.
Pulling code from Unison Share
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. Thepull
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 andpull
a different version.