Contributions under the form of new packages, issue reports and pull requests to fix and enhance the quality of packages are always welcome. Thanks for your time and involvement.
Becoming the maintainer of orphaned packages is easy and very welcome.
The following lists a few points that help in making the contribution process and repository management as smooth and efficient as possible for everyone involved.
Note that if your have an issue with the opam tool itself this should not be filed here but on the opam tool issue tracker.
To report package installation issues:
- First try to search the issue tracker to see if someone already reported the issue. If that is the case mention on this issue that you are also affected and, if available, add more diagnostic details.
- If you create a new issue make sure the issue title mentions the package name and the affected version.
- Try to give as much information as possible about your setup in
the issue body:
- Add the output of
opam config report - Add the exact opam invocation and the resulting tool output.
- Add the output of
If you happen to have a fix for a package, please have a look at the issue tracker to see if it doesn't concern an existing issue. If that is the case mention it in your pull request.
Information about creating new packages and adding them to repository is available in opam's manual.
If you are using dune and hosting your git repository on github you can use the following tutorial that provides a step-by-step procedure to
make a hello package available in opam.ocaml.org.
If you are not using dune or hosting your project on github you can still use opam-publish as described by the manual page linked above.
The top-level sources contain the following files with the opam file having the same name of the project.
$ ls hello/
src/
dune
dune-project
hello.opam
A quick summary of the steps to be followed are listed below:
$ dune build
$ dune-release lint
$ dune-release tag
$ dune-release distrib
$ dune-release publish
$ dune-release opam pkg
$ dune-release opam submit
We will now go through each of the above commands in detail:
dune build
The OCaml source package needs to be built with dune, dune-project
and .opam files along with the sources. The build should be
successful before proceeding further. For example:
$ dune build
Done: 56/61 (jobs: 1)
dune-release lint
The lint command checks for the presence of meta files in the
project folder, and also runs opam lint. A sample output is given
below for your reference:
$ dune-release lint
[ OK ] File README is present.
[ OK ] File LICENSE is present.
[ OK ] File CHANGES is present.
[ OK ] File opam is present.
[ OK ] lint opam file hello.opam.
[ OK ] opam field description is present
[ OK ] opam fields homepage and dev-repo can be parsed by dune-release
[ OK ] Skipping doc field linting, no doc field found
[ OK ] lint /home/guest/hello success
You need to fix any errors reported by linting, and commit the changes locally.
dune-release tag
A ChangeLog CHANGES file is required, and the format used is
available in the
dune-release
documentation. A minimal example is as follows:
$ cat CHANGES
## v0.0.1 (2021-02-23)
### Added
- Meta files for dune release
After updating the CHANGES file, you need to tag the release. You will be prompted to confirm the version, as can be seen in the following output:
$ dune-release tag
[-] Extracting tag from first entry in CHANGES
[-] Using tag "v0.0.1"
[?] Create git tag v0.0.1 for HEAD? [Y/n]
Y
[+] Tagged HEAD with version v0.0.1
dune-release distrib
The sources are then archived to create a distribution as illustrated below:
$ dune-release distrib
[-] Building source archive
[+] Wrote archive _build/hello-v0.0.1.tbz
[-] Linting distrib in _build/hello-v0.0.1
[ OK ] File README is present.
[ OK ] File LICENSE is present.
[ OK ] File CHANGES is present.
[ OK ] File opam is present.
[ OK ] lint opam file hello.opam.
[ OK ] opam field description is present
[ OK ] opam fields homepage and dev-repo can be parsed by dune-release
[ OK ] Skipping doc field linting, no doc field found
[ OK ] lint _build/hello-v0.0.1 success
[-] Building package in _build/hello-v0.0.1
Done: 56/60 (jobs: 1)[ OK ] package builds
[-] Running package tests in _build/hello-v0.0.1
Done: 0/0 (jobs: 0)[ OK ] package tests
[+] Distribution for hello 0.0.1
[+] Commit c9935ac42271ce23cc422c299c5c3aaf92646499
[+] Archive _build/hello-v0.0.1.tbz
dune-release publish
You can now publish the distribution to your GitHub repository as follows:
$ dune-release publish
[-] Skipping documentation publication for package hello: no doc field in hello.opam
[-] Publishing distribution
[-] Publishing to github
[?] Push tag v0.0.1 to [email protected]:guest/hello? [Y/n]
Y
[-] Pushing tag v0.0.1 to [email protected]:guest/hello
[?] Create release v0.0.1 on [email protected]:guest/hello? [Y/n]
Y
[-] Creating release v0.0.1 on [email protected]:guest/hello via github's API
[+] Succesfully created release with id 38465706
[?] Upload _build/hello-v0.0.1.tbz as release asset? [Y/n]
Y
[-] Uploading _build/hello-v0.0.1.tbz as a release asset for v0.0.1 via github's API
dune-release opam pkg
The .opam file can then be generated using the following command:
$ dune-release opam pkg
[-] Creating opam package description for hello
[+] Wrote opam package description _build/hello.0.0.1/opam
dune-release opam submit
The ~/.config/dune/release.yml file should then be updated with your
opam repository settings as indicated below (in particular, change <username> by your local username and <github-user> by your own github username):
$ cat ~/.config/dune/release.yml
user: <username>
remote: [email protected]:<github-username>/opam-repository.git
local: /home/<username>/.cache/dune/opam-repository/
You can now submit your package to be included to opam.ocaml.org using the following command, which will create a new pull request to ocaml/opam-repository:
$ dune-release opam submit
[-] Submitting
[-] Preparing pull request to ocaml/opam-repository
[-] Fetching https://github.com/ocaml/opam-repository.git#master
[-] Checking out a local release-hello-0.0.1 branch
[-] Pushing release-hello-0.0.1 to [email protected]:guest/opam-repository
[?] Open PR to ocaml/opam-repository? [Y/n]
Y
[-] Opening pull request to merge branch release-hello-0.0.1 of [email protected]:guest/opam-repository into ocaml/opam-repository
Congratulations on submitting your first OCaml package!
Orphaned packages either have no maintainer: field or the field is
set to the repository issue tracker:
maintainer: "https://github.com/ocaml/opam-repository/issues"
If you care about a package and it is orphaned we are keen on having
you as the maintainer of the package. In order to do so simply issue a
pull request on the latest version of the package and add your contact
details in the maintainer: field.
If it is no longer possible for you to commit to maintain a package you can either:
- Try to find a person to replace yourself in that role. Let her
issue a pull request that updates all the
maintainer:fields that contain your details with her own and do acknowledge the transfer on her pull request. - Or, if you cannot find someone to replace you, simply issue a pull
request that updates all the
maintainer:fields that have your details with the address of the repository issue tracker (see above).
If your question about contributing is not answered here, please post on the
https://discuss.ocaml.org forum in the ecosystem category with your query.
Beginners questions are welcome there, particularly since we can use your
question to refine the documentation of the project.