b0 release manual

The .release unit provides tools to publish source software releases. The release support is rather generic but the release script here specifically talks about submitting the software to the opam repository. You can skip these steps if you are doing something different.

TODO. Review an adapt. Mainly taken from the topkg-release man page.

Release script

In the simplest case if you just have one package to release:

b0 browse issues          # Review remaining outstanding issues
b0 -- .release status     # Review the changes since last version
$EDITOR CHANGES.md        # Edit the release notes
git commit -m 'Prepare release.'
b0 -- .release tag        # Tag the release with a version
b0 -- .release archive    # Create the release archive
b0 -- .release publish    # Publish it on the WWW with its documentation
b0 -- .opam submit

Note worflows is able to handle the following cases:

• Your b0 file gathers the B0.ml file of multiple projects in different VCSs.
• You need to publish multiple packages from a single release archive.

We do not describe this advanced usage here but checkout the the --help of the various commands to see how they behave.

Preparing the release

First have a look at the outstanding issues the package may have by checking the issue tracker with this command.

b0 browse issues

This open in your browser the URLs specified in the B0_meta.issues field of the packs of the B0.ml file in your browser.

Write the release notes

Carefully write the release notes in the package's change log. These are essential time savers for users of the package. The list of changes that were comitted since the last VCS version tag can help:

b0 -- .release status

You can then write the release notes and commit them to the VCS with:

$EDITOR CHANGES.md
git commit -m 'Prepare for release."

VCS tag the release

Basic checks are performed on the release archive when it is created, but save time by catching errors early. Hence test that your source repository lints and that it builds in the current build environment and that the package tests pass. FIXME we should have a .release check.

b0 -- .opam file  # Regenerate opam file
b0 -- .ocaml META # Regenerate META file (TODO get rid of that)
b0                # Build the project
b0 lint           # Lint the project
b0 test           # Run the default test suite

The following command simply extracts the latest version tag from the package's change log and tag the VCS HEAD commit with it:

b0 -- .release tag

This will only work if the change log follows a certain format, see b0 -- .release tag --help for details. But bascially this extracts the first token of the first heading of the changes file.

You can check the extracted tag is the one you wish before with:

b0 -- .release tag --dry-run

If you do not want to rely on B0_release's appromative extraction algorithms just specify it on the command line:

b0 -- .release tag v1.0.1

You can also choose to use your VCS directly. But this worfklow ensures that your wrote up-to-date release notes describing a correct version number.

Create the release archive and publish it

Now that the release is tagged in your VCS, generate a distribution archive for it in the build directory with:

b0 -- .release archive

This uses the source tree of the HEAD commit for creating a distribution in the build directory. The distribution version string is the VCS tag description (e.g. git-describe(1)) of the HEAD commit. Alternatively it can be specified on the command line.

If everything went well you can now publish the distribution and its documentation on the WWW. The exact actions that happen here depend on the package's delegate, see topkg-delegate(7) for more details.

b0 -- .release publish

The release archive is now public. This also pushes the VCS repo and its tags.

Submit to OCaml's opam repository

To publish the archive to the OCaml opam repository it's now simply a matter of:

b0 -- .opam publish

There are however details you need to be aware and some setup will be needed in the first time. See the details in the b0 opam manual.

Also this will download the software you just published back to your computer. It may seem wasteful but it makes sure everything is properly setup to work for others.

Troubleshooting

Here are a few troubleshooting scenarios and possible resolution.

Before publishing

Anything that happens before the .release publish step, like a failing .release archive, is easy to resolve. Delete the version tag of your VCS e.g. with:

b0 -- .release tag -d
b0 -- .release tag -d --dry-run # If you are unsure

Add some commits, adjust your release notes and start over.

On reproducible archives

Given the archive name, the release commit identifier and the version string, archive produced by .release archive command should always generate the same archive:

• Files are added to the archive using a well defined order on paths.
• File permissions are 0o664 or 0o775 for directories and files that are executable for the user.
• File modification times are set to the commit date (note that if git is used, git-log(1) shows the author date which may not coincide).
• No other file metadata is recorded in the tar archive.

This should ensure that the resulting archive is bit-wise identical regardless of the context in which it is created. However this may fail for one or more of the following reasons:

• Non-reproducible archive hook. If the archive hook relies on external factors that are not captured by the source repository checkout. For example external data files, environment variables, etc.
• File paths with non US-ASCII characters. These paths are encoded in UTF-8, different file systems may return the paths with different Unicode normalization forms which could yield different byte serializations in the archive (this could be lifted at the cost of a dependency on a Unicode normalization library).
• The compression utility. The archive is compressed using the bzip2 utility. Reproducibility relies on bzip2 to be a reproducible function across platforms.
• B0_release changes. B0_release could change its distribution procedure in the future, for example to correct bugs.