https://github.com/tarides/dune-release
Streamlining the release of dune packages to opam
https://github.com/tarides/dune-release
opam release
Last synced: 5 months ago
JSON representation
Streamlining the release of dune packages to opam
- Host: GitHub
- URL: https://github.com/tarides/dune-release
- Owner: tarides
- License: isc
- Created: 2018-04-12T16:27:43.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2024-07-30T13:59:29.000Z (about 1 year ago)
- Last Synced: 2024-11-08T13:03:36.079Z (11 months ago)
- Topics: opam, release
- Language: OCaml
- Size: 1.35 MB
- Stars: 115
- Watchers: 11
- Forks: 37
- Open Issues: 85
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-list - dune-release
README
[](https://ocaml.ci.dev/github/tarides/dune-release)
## dune-release: release dune packages in opam
`dune-release` is a tool to streamline the release of Dune packages in
[opam](https://opam.ocaml.org). It supports only projects be built
with [Dune](https://github.com/ocaml/dune) and released on
[GitHub](https://github.com).
## Installation
`dune-release` can be installed with `opam`:
```
opam install dune-release
```
## Documentation
The `dune-release` command line tool is extensively documented in man pages
available through it's help system. Type:
```
dune-release help release # for help about releasing your package
dune-release help # for more help
```
Calling `dune-release` without any argument will start the automated release process, composed of the following steps:
- create the distribution archive;
- publish it online;
- create an opam package;
- submit it to OCaml's opam repository.
If the repository contains multiple opam packages, `dune-release` will try to release all of them by default (ie. one tarball, one github release but several opam files added to the opam repository).
The most basic workflow is:
```
dune-release tag
dune-release
```
Each step is refined and explained with more details below.
By default `dune-release` asks for permission before taking any significant action so you should not be afraid of running it.
### Tag the distribution with a version
This step should be executed prior to running the `dune-release` automated process.
The tagging command of `dune-release` will extract the latest version tag from the package's change log and tag the VCS HEAD commit with it if it is invoked without argument:
```
dune-release tag
```
This will only work if the change log follows a certain format.
The version number must be in the first item of the change log file (usually a section title). Asciidoc and Markdown files are supported. A typical example of such version in a markdown file is:
```
## v1.0.1 (2019-09-30)
```
The version extracted from this change log will be `v1.0.1`. This will be used to infer the tag of the release as well as generate the publication message. If you do not want to rely on this extraction you can specify it on the command line:
```
dune-release tag v1.0.1
```
You can also directly use your VCS instead if the `dune-release tag` command does not fit your needs.
Note that `dune-release` and `dune` only work with annotated tags (i.e. tags created with
`git tag -a`) and that if you want to take care of the tagging yourself you should take this into
account.
If you need to delete a tag created by `dune-release`, use the following command:
```
dune-release tag -d v1.0.1
```
The full documentation of this command is available with
```
dune-release help tag
```
### Create the distribution archive
Now that the release is tagged in your VCS, generate a distribution archive for it in the build directory with:
```
dune-release distrib
```
This uses the source tree of the HEAD commit for creating a distribution in the build directory.
Note that any uncommitted change will therefore be ignored. The distribution version string is the
VCS tag description (e.g. `git-describe`) of the HEAD commit. Alternatively it can be specified on
the command line.
Basic checks are performed on the distribution 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.
```
dune-release check
```
The full documentation of this command is available with
```
dune-release help distrib
```
### Publish the distribution online
Once the distribution archive is created you can now publish it with:
```
dune-release publish
```
This means creating a Github release associated with the tag and upload the distribution tarball as a release artifact.
The full documentation of this command is available with
```
dune-release help publish
```
#### Publish troubleshooting
If github returns a `Permission denied` error during `dune-release publish`, the reason is probably a failing ssh connection. In that case, we suggest that you set up ssh. If you prefer not to and you've already set up https instead, we suggest that you configure git as follows:
```
git config [--global] url."https://github.com/".pushInsteadOf "git@github.com:"
```
Running that line once will configure git to always push over https - either for that repository or globally.
In more detail: `dune-release publish` always pushes to github over ssh by explicitly giving git the github uri of your project with ssh prefix (`git@github.com:`). By configuring git as suggested above, git will automatically replace that prefix by the https one when pushing and push over https instead.
### Create an opam package and submit it to the opam repository
To add the package to OCaml's [opam repository](https://github.com/ocaml/opam-repository), we start by creating an opam file to be used on the opam repository. This file includes the download URI for the distribution tarball and the tarball hash:
```
dune-release opam pkg
```
To submit the package to the opam repository and create the associated pull request we run:
```
dune-release opam submit
```
The full documentation of this command is available with
```
dune-release help opam
```
### Important Notes
Most of the code in this repository has been written and has already
been released part of the [topkg](http://erratique.ch/software/topkg)
tool.
The main differences between `dune-release` and `topkg` are:
- Remove `pkg/pkg.ml`;
- Assume the project is built with [dune](https://github.com/ocaml/dune);
- Bundle everything as a single binary;
- Use of `Astring`, `Logs`, `Fpath` and`Bos`;
- Remove the IPC layer (which is used between `topkg` and `topkg-care`);
### Runtime dependencies
- `bzip2` can be set with the `DUNE_RELEASE_BZIP2` variable (deprecated), otherwise it is expected to be in `PATH`;
- `tar` can be set with the `DUNE_RELEASE_TAR` variable (deprecated), otherwise it is expected to be in `PATH`;
- `git` can be set with the `DUNE_RELEASE_GIT` variable (deprecated), otherwise it is expected to be in `PATH`;
- `hg` can be set with the `DUNE_RELEASE_HG` variable (deprecated), otherwise it is expected to be in `PATH`;
- `opam` can be set with the `HOST_OS_OPAM` variable (deprecated), otherwise it is looked for in `HOST_OS_XBIN/opam` (deprecated), otherwise it is looked for in `opamHOST_OS_SUFF` (deprecated), otherwise it is expected to be in `PATH`;
- `dune`, `curl`, `cp` and `ocamlfind` are expected to be in `PATH`.
Using these `DUNE_RELEASE_*` and `HOST_OS_*` environment variables to configure the path to these binaries is deprecated since `dune-release.1.4.0`, and will no longer be supported in `dune-release.2.0.0`, it is thus recommended to only rely on the `PATH` variable.
## Contributing
While this project is in the [Tarides](https://tarides.com) organization, contributions from others
are very much welcome. We're trying to build a tool that works for many users.
If you're unclear whether a feature would fit the scope of `dune-release` don't
hesitate to open an issue to gauge the interest.
Please read the [guidelines](CONTRIBUTING.md) before contributing.