Publishing a release of a project

Releases are like immutable snapshots of a given branch. They do not contain the history of the project so other libraries can depend upon them without using additional space in their codebase.

There are two ways to create a release of a project, the recommended option is to use the Unison Share UI to create a release, and the other is using the release.draft command.

Creating a release from the Unison Share UI

If you are intending to create a release using only the Unison Share UI and you'd like to associate release notes with the new version, make sure your ReleaseNotes document term is up to date with the latest changes to your library. Push main up to Unison Share and head to the "releases" tab for the project.

Image of the releases page with a "cut a release" button at the top.

Click the "Cut a release" button to open the release version modal.

You'll have some options for how to version the next release. Increment your release by one major, minor, or patch version.

Image of the release version modal.

Hit publish and Unison Share will create a new release for you! The release process will squash the unneeded codebase history when it creates the release, so users of your library will have a compact version to depend on.

Creating a release draft in the UCM

You can create a release from any branch of a project, but it's common to create a release from the main branch in the UCM. To start a release, use the release.draft command and enter the version number of the release you want to create.

myProject/main> release.draft 1.0.0

This will create a new branch called /releases/drafts/1.0.0.

You may want to add a Doc term called "ReleaseNotes" to this branch at this point to describe the changes in this version. Upon publication, if Unison Share finds a term called "ReleaseNotes" in a release branch, it will display the notes for others to benefit from.

ReleaseNotes = {{

  * Added function {List.map}
  * Updated function {List.filter}
  ...

}}

After you're done adding the release notes, push the branch to Unison Share and head to the project url given in the console.

myProject/releases/drafts/1.0.0> push

The "releases" tab for the project has a special section for "draft" releases at the top if a branch matching the release draft naming conventions is found. Click publish for the release draft in question to open up a modal for confirming the desired version. Otherwise you can use the "cut a release" button found in the "releases" page to make a release at any time.

Image of the releases page with a draft release at the top.

Unison Share supports semantic versioning for releases, so pick one of the options given in the modal.

Image of the release version modal.

When you're ready, hit "Publish" and Unison Share will add your new version to the list of releases for a project.