Merge pull request #100 from dune-universe/update-doc

Update the release process in the README

README.md

@@ -8,8 +8,7 @@ It's meant to be used by the [`opam-monorepo`](https://github.com/ocamllabs/dune
 tool to allow you to vendor your dependencies and build your entire project
 using `dune` only.
 
-There is a merged repository that the `duniverse` tool uses which is a
-standalone opam repository at
+There is a merged repository at
 <https://github.com/dune-universe/opam-repository> (in the `duniverse` branch).
 
 All packages' versions in this repository are suffixed with a `+dune` to
@@ -23,37 +22,39 @@ The typical workflow to port an existing package to dune and publish it on
 `opam-overlays` would be the following:
 
 1. Create a fork of the upstream package `abc`
-2. Port it to dune on a specific branch `dune-universe-vX.Y.Z`, where `X.Y.Z` corresponds to the upstream
-   version you're dunifying. Make sure the opam file has been properly updated and that dune is now part of the package
-   `depends` field and the `dev-repo` field is set to your fork.
-3. Open a PR to `opam-overlays` adding a `packages/abc/abc.X.Y.Z+dune/opam` containing:
-```
-url {
-  src: "git+https://github.com/<your_username>/abc.git#<branch_name>"
-}
-```
-
-Remove any older versions of a package, since we only maintain a single one per
-package here.  All packages must also be coinstallable simultaneously, which is
-verified by the CI.
+2. Port it to dune on a specific branch `dune-universe-vX.Y.Z`, where `X.Y.Z`
+   corresponds to the upstream version you're dunifying. Make sure the opam file
+   has been properly updated and that dune is now part of the package `depends`
+   field and the `dev-repo` and `homepage` point to your fork. It is also
+   recommended to remove the `doc` field to ease the rest of the release
+   process.
+3. Tag it with `X.Y.Z+dune`.
+4. Use `dune-release` to release your port to this repo as described in the
+   below section.
 
-## Release an existing port to `opam-overlays`
+## Releasing to this repo using dune-release
 
-This is basically done by jumping straight to the above step `3` using the tag
-or branch under which the dune port lives in the forked repo.
+### Preliminary steps
 
-If the opam file's `dev_repo` and `depends` haven't been properly updated, make
-sure to fix it in the `packages/abc/abc.X.Y.Z+dune/opam`.
+If this is the first time you are releasing to `dune-universe/opam-overlays`
+you will need to do the following first:
+1. Clone this repository on your machine
+2. Fork of this repo on Github
 
-## Deleting a package
+### Releasing
 
-When the dune version is merged upstream to
-https://github.com/ocaml/opam-repository, simply remove the port here.
+Once your dune port is ready and you tagged it with `X.Y.Z+dune`, you can run
+the following:
+```
+dune-release --opam-repo dune-universe/opam-overlays --remote <url to your fork> --local <path-to-your-clone>
+```
 
-## Merging to live duniverse
+We strongly recommend you delete the doc field from the opam file when doing
+the port as dune-release will otherwise try to publish the documentation.
+This is both not needed and can lead to errors.
 
-Run `./merge-to-opam-repo <repodir>` and it will push to dune-universe/opam-repository
-and rebase the `duniverse` branch.
+dune-release 2.0.0 will simplify this workflow greatly but in the meantime
+please bear with us!
 
 ## Support