Explain how to get token from opam-publish

[talex5]

https://mirage.io/wiki/packaging says:

Run opam-publish once to generate a release token.

But:

$ opam-publish 
Opam-publish v.0.3.5

Sub-commands:
      prepare URL   Prepares a local package definition directory from a
                    public URL pointing to a source archive.
      submit DIR    Submits or updates the request for integration of
                    the package defined by metadata at DIR.
      repo          Manage the repos you contribute to.

See 'opam-publish COMMAND --help' for details on each command.

How do I get the token?

[talex5]

This seems to work:

Use the GitHub web interface to request a "Personal access token" and save this as ~/.opam/plugins/opam-publish/$USER.token, where USER is your GitHub username. This file's contents will be a single line containing just the token.

public_repo appears to be the only scope required.

[talex5]

Additional notes:

• The token file MUST NOT contain an end-of-line character. If it does, it will be automatically deleted and you will have to create another one. In vi, set binary noeol will allow you to save the token correctly.
• topkg will force-push ALL branches and tags in your repository, without confirmation, so first make a fresh clone and do the release from there to avoid losing any work or pushing unwanted tags and branches.
• topkg publish will overwrite your gh-pages branch (I think). Use topkg publish distrib if you want to keep your existing site.
• From the topkg docs, it looks like it searches for a token with your username. In fact, it uses the first token it finds matching the pattern *.token.
• Be sure to tag with topkg tag, not git tag, as it uses git describe to generate the name and that ignores light-weight tags.
• topkg opam submit only submits one package in a multi-package repository. To release multiple packages, use: Submit transaction ocaml-opam/opam-publish#38 (comment)

[samoht]

We do not mention opam-publish anymore on that page, so closing. Feel free to improve the new page if instructions are not clear enough!