Facilitating Preview Package Publication from Forks

[mbarbin]

Hello,

I've been exploring a workflow that allows the creation and publication of
preview packages to a custom opam repository for the pull requests I'm working
on. The aim is to streamline the testing process, including the ability to
preview the impact of a new version in dependent repositories, create PRs, and
pull the package from GitHub actions in CI, among other things.

This workflow has proven to be quite beneficial. Despite having robust tests,
issues often surface only when a package is used in a real-world scenario. This
workflow increases the likelihood of identifying issues earlier, while the
changes are still under review or even during the draft PR stage. It also
facilitates progress on dependencies without waiting for a package release,
potentially boosting overall productivity.

I'd like to invite more developers to try this workflow and propose some
enhancements to dune-release to simplify its implementation.

I've been leveraging dune-release for most of the steps in this workflow and
have found its CLI's modularity extremely useful. I'll outline the steps
involved and identify which ones could benefit from modifications to better
support this workflow.

Workflow for Creating a Preview Package from a Fork

Pre-requisite

Assume you have a forked repository where you've made some changes, including a
commit to prepare the changelog for publishing a preview package for testing,
with the intended name.

For illustration, I'll use ocaml-grpc.0.2.1-preview.2, created from changes from this Draft PR.

Release Steps

Distrib Creation

In a local clone of my fork, I executed:

$ dune-release tag
$ dune-release distrib

These steps, executed within a fork clone, work perfectly without any modifications. This resulted in the creation of _build/grpc-0.2.1-preview.2.tbz.

Distrib Publication

$ dune-release publish distrib

This step is problematic as it prompts to push the tag to the original repo
(dialohq/ocaml-grpc), not my fork. I
had to abort the command at this point. I suspect it would then attempt to
create a release in the original repo, which is not the desired outcome.

Instead, I manually created a release on GitHub via the Web UI and attached the
distrib file created in the previous step, resulting in a functional release.

Opam File Creation

After this, I found the URL where the distrib file was published and added this
link to the _build/asset-0.2.1-preview.2.url file in my local clone. This file
will be used by the next dune-release opam pkg invocation.

Typically, this file is an artifact of the publish distrib command, but since
it couldn't run, we manually create the file to resume the regular
dune-release sequence.

echo https://github.com/mbarbin/ocaml-grpc/releases/download/0.2.1-preview.2/grpc-0.2.1-preview.2.tbz > _build/asset-0.2.1-preview.2.url

$ dune-release opam pkg

This step works well (assuming it can find the *.url file created above),
generating all the *.opam files for the preview package.

Package Publication to the Custom Opam Repository

$ dune-release opam submit --opam-repo=GITHUB_USER_OR_ORG/REPO_NAME

In my case, this step fails due to #482. However, if your default branch is
master, you should be able to use dune-release for this step.

Instead, I manually committed the opam files and pushed them to my custom opam
repository, as seen in this commit.

From there, the package can be used in any opam switch by adding the repo
accordingly:

opam repo add mbarbin https://github.com/mbarbin/opam-repository.git

Proposed Changes

If dune-release publish distrib offered a flag to override the repo URL for
distrib publication, it would suffice. A brief look at the code suggests that
the command infers this information from the dev-repo field of the opam file.

It might be feasible to modify this (possibly sourced from the source property
in the dune-project?) locally as part of the commit that prepares the release
notes. Since this commit isn't intended to be part of the pull request, it could
be a viable enhancement to the workflow described above. I haven't tested this
yet.

If this workflow proves to be useful and gains popularity, it would be beneficial
to consider supporting a higher-level command in dune-release that encapsulates
this sequence of operations, leveraging the modularity of the CLI for a more
streamlined user experience.

Thank you for dune-release!