this repo has no description
anil.recoil.org
1Contributing to the OCaml opam repository
2-----------------------------------------
3
4Contributions under the form of new packages, issue reports and pull
5requests to fix and enhance the quality of packages are always
6welcome. Thanks for your time and involvement.
7
8Table of content:
9* [Add a new package](#add-a-new-package)
10* [Fixing packages](#fixing-packages)
11* [Governance](#governance)
12* [Policies](#policies)
13* [How to deal with CI](#how-to-deal-with-ci)
14
15Add a new package
16-----------------
17
18There are several ways to add a new package to opam-repository.
19You can either use a tool such as `dune-release` or `opam-publish`, or open a PR manually.
20Each ones have their strengths and weaknesses. For example:
21* `dune-release` is a tool more focused into helping people do their whole release process from start to finish for them. To that end it:
22 * helps with tagging
23 * parses (and enforces a format, can be good or bad) for the changelog, to put it in the tag
24 * creates the github release with that information
25 * builds, run tests, lint
26 * creates and uploads a separate archive (also has an option to include the git submodules)
27 * works only if your project is on GitHub
28 * doesn’t support force-pushed tags
29* `opam-publish` is a more malleable tool focused on publishing. To that end it:
30 * works for any type of projects (you can just use a custom archive as an argument)
31 * simpler to use than dune-release
32 * more focused tool so you should encounter less issues and resistance but it’s more manual
33 * only handles the opam linting and publishing
34* you can also open a PR manually:
35 * this one gives you the most freedom. It is only recommended for experienced users
36 * this is however currently the only way to fix packages (as opposed to adding packages). See the appropriate section below
37
38We'll cover each ones in the following subsections:
39
40### using dune-release
41
42*if you encounter any issues, please read [dune-release's README](https://github.com/tarides/dune-release/blob/main/README.md)*
43
44First, make sure your project is using dune and is hosted on GitHub.
45Then, make sure you’ve forked opam-repository on GitHub. If not go to https://github.com/ocaml/opam-repository/fork
46Then, create a new file in `~/.config/dune/release.yml` with the content as indicated below, change `<username>` by your local username and `<github-username>` by your own github username:
47```
48remote: git@github.com:<github-username>/opam-repository.git
49local: /home/<username>/.cache/dune/opam-repository/
50```
51Then, you can tag the release using:
52```
53dune-release tag
54```
55Once done, you can simply call:
56```
57dune release
58```
59If all goes well this should create the Release on GitHub and open the PR to publish the package on opam-repository.
60
61For any subsequent releases only the last two steps are necessary.
62
63### using opam-publish
64
65*if you encounter any issues, please read [opam-publish's README](https://github.com/ocaml-opam/opam-publish/blob/master/README.md)*
66
67Once you have done your release and have an archive available publicly on the internet, simply call:
68```
69opam-publish <url>
70```
71This will open the PR to publish the package on opam-repository.
72
73For other options, please refer to `opam-publish --help`
74
75### publish manually
76
77An opam repository is a tree-like structure of directories and files as follow:
78```
79./
80|- packages/
81 |- pkgname/
82 | |- pkgname.2.0/
83 | |- opam
84 |- another-pkgname/
85 |- another-pkgname.1.0.0/
86 | |- opam
87 |- another-pkgname.1.0.1/
88 |- opam
89|- ...
90```
91So to add a package, simply create a directory with your package name (pkgname) and version
92```
93mkdir -p packages/pkgname/pkgname.version/
94```
95once done, copy the opam file for said package into the newly created directory.
96Edit that copied opam file by removing redundant or forbidden fields such as `name`, `version`, `pin-depends` if present, as well as adding or editing the `url` section as follow:
97```
98url {
99 src: "https://a.publicly-accessible.url/your-archive.tar.gz"
100 checksum: [
101 "sha256=the-sha256-hash-of-your-archive"
102 "sha512=the-sha512-hash-of-your-archive"
103 ]
104}
105```
106we recommend using more than one checksum and at least sha256 or stronger. Opam currently supports only md5, sha256 and sha512.
107
108Optionally you might want to integrate external files (such as patches). You will need to host them on your server, or https://gist.github.com, or https://github.com/ocaml/opam-source-archives.
109
110Add the file you uploaded to the [extra-source](https://opam.ocaml.org/doc/Manual.html#opamsection-extra-sources) section of the opam file as follow:
111```
112extra-source "the-filename" {
113 src: "https://my-server/my-file"
114 checksum: [
115 "sha256=the-checksum-for-my-file"
116 ]
117}
118```
119
120If you like to have this file being applied as a patch to the source tree after unpacking, you also need to specify in the opam file:
121```
122patches: [ "the-filename" ]
123```
124
125If you don't specify it as `patches`, the file will be copied to the source directory after unpacking - and be available when building the package.
126
127Once all that is done, you need to create a new git branch, commit your change, push it to your own fork
128```
129git switch -c release-yourpkg-version
130git add packages/yourpkg/yourpkg.version/
131git commit -pm "Release yourpkg.version"
132git remote add your-github-handle git@github.com:your-github-handle/opam-repository.git
133git push your-github-handle release-yourpkg-version
134```
135and open a PR on opam-repository on GitHub. Congratulations!
136
137For more technical information about opam files, please read the [opam manual](https://opam.ocaml.org/doc/Manual.html)
138
139Fixing packages
140---------------
141
142Packages are fixed as soon as they show up as broken in opam-repository CI or in the repository issues, if the opam-repository maintainers have time.
143If, as an external contributor, you are willing to help out, you can send a PR to fix the packages that are broken. This is extremely helpful.
144
145There are several types of fixes:
146* **Changes to the metadata** (e.g. `homepage`, `synopsis`, …) are simple, usually harmless and easy to do and get merged.
147* **Changes to the dependencies or availibility** require some scrutiny from the opam-repository maintainers to verify that the new constraints are correct and do not break existing working installations.
148* **Changes to the way the package is built** (e.g. changes to the build rules, addition of patches, …) require a lot more scrutiny from the opam-repository maintainers and maybe a new revision.
149* **Changes to the source archive(s)** is prohibited but in the case where there is no other choice and the checksum is not the same, the difference with the original must be negligable.
150
151**PSA**: if the PR envisioned is large or involved, please ping the maintainers beforehand.
152
153**IMPORTANT**: If you are maintaining a package that you want to fix, never change the source archive pointed by a package that has already been merged in opam-repository. This would otherwise break anyone who is trying to install it and the archive's checksum would change which renders the installation impossible. Sending a PR in opam-repository that change this checksum is **prohibited** (see [wiki/Policies](https://github.com/ocaml/opam-repository/wiki/Policies)). Instead, if the already released version is broken in some way you can send a PR making it `available: false` and make a new point-release. If this is really too complicated or impossible, you can also send a patch.
154
155#### Revisions
156
157Revision versions are packages whose version is of the form `<version>-<revision>` with the revision number typically starting at 1.
158They typically provide a slightly modified version of an original release.
159
160For example `pkg.1.0.0` is not maintained anymore (be it this specific version or the package as a whole), and someone would like to provide a patch to fix something that some people might rely on even if it might be a buggy behaviour. In this case the package is duplicated into the original version (left untouched) and the revision with the fix. This way, if the fix broke someone's setup they case still use the original version.
161
162#### Patches
163
164To fix packages, patches might sometimes be useful. This can be given to a package through the [patches field](https://opam.ocaml.org/doc/Manual.html#opamfield-patches), and added through the [extra-source section](https://opam.ocaml.org/doc/Manual.html#opamsection-extra-sources).
165
166As a rule of thumb, unless urgent, the patch should go through upstream first and only if the maintainer is not responding in a reasonable timeframe, we can then think about including the patch in opam-repository, the focus should be for upstream to do a new release.
167
168As an external contributor looking to patch a package, whose maintainer do not agree with it or is unresponsive, another solution could be to fork the project or ask the current maintainer to transfer the maintenance to you.
169
170Governance
171----------
172
173The current points of contact and the full list of maintainers is available in [./governance/README.md](./governance/README.md).
174Information about the infrastructure is available in [wiki/Infrastructure-info](https://github.com/ocaml/opam-repository/wiki/Infrastructure-info).
175
176Typically maintainers gather weekly to discuss ongoing topics, review PRs together and train maintainers in training.
177If you wish to help and become an opam-repository maintainer, you can send a message to the maintainers listed above and you will be invited to the next meeting in which they will explain how things work.
178
179Policies
180--------
181
182Maintainers enforce a certain number of policies applied on packages in opam-repository.
183You can read about them in [./governance/policies/](./governance/policies/).
184
185How to deal with CI
186-------------------
187
188When you open a PR, a number of checks are done to verify that builds and runs correctly on a number of different platforms.
189You can read about how to deal with our CI (Continuous Integration) in [wiki/How-to-deal-with-CI](https://github.com/ocaml/opam-repository/wiki/How-to-deal-with-CI).