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. Run
auth.loginin the UCM locally.
This will open your default web browser and prompt you to log into Unison Share.
To push your own project to Unison Share, use the
pushcommand from inside the project and optionally include the branch you're hoping to publish. This pushes the
mainbranch to @username/myProject/main.
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 the
pushcommand 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
.> 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 should
clonethe project to keep in sync with active development and should createcontributor branchesinstead of pushing directly to the
mainbranch. 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 the
mainbranch represents the latest work in progress, feature branches are used for concurrent workstreams, and release branches or release drafts are snapshots of the
mainbranch at a given point in time.
releases/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
mainbranch of your project, located just under the project root, you should have a
libnamespace to contain your library's dependencies. Optionally you can include a
READMEdocumentat 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
ReleaseNotesterm in your project, it will automatically attach it as the release notes for the latest version of your library.
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
releases/X.Y.Zbranch is a special branch that is created by Unison Share which squashes the history of the
mainbranch 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. The
pullcommand 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
pulla different version.