Unison Share code hosting

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.loginin 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 thepushcommand from inside the project and optionally include the branch you're hoping to publish. This pushes themainbranch 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 thepushcommand 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 thepublicnamespace.

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

Image of the Project settings page with a visibility option.

Currently, Unison Share does not have the concept of "organizations" but projects can still be collaborated on by multiple individuals. Fellow maintainers shouldclonethe project to keep in sync with active development and should createcontributor branchesinstead of pushing directly to themainbranch. 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 themainbranch represents the latest work in progress, feature branches are used for concurrent workstreams, and release branches or release drafts are snapshots of themainbranch at a given point in time.

Note, themainandreleases/X.Y.Zbranches are special branches that are created for you when you initialize or publish a project, repsectively.

     -- branch off of main
     -- snapshots of main

Read more the recommended project structure here.

Inside themainbranch

Within themainbranch of your project, located just under the project root, you should have alibnamespace to contain your library's dependencies. Optionally you can include aREADMEdocumentat 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 aReleaseNotesterm 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.Zbranch is a special branch that is created by Unison Share which squashes the history of themainbranch into a simple snapshot.

Read more about creating library releases here.

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.

You should consider featuring your own work on the Unison Share front-page catalog! Head to the#libraries channel in the Unison slackand ping@hojbergwith a link to your project.

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. Thepullcommand 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 andpulla different version.

Image of the Use Project modal.
If you're pulling a library dependency into your code, you must put it in thelibnamespace in your project.

Read more about pulling code from Unison Share here.