this repo has no description
Rewrite CONTRIBUTING.md
+134
-222
+132
-210
CONTRIBUTING.md
+132
-210
CONTRIBUTING.md
···
5
5
requests to fix and enhance the quality of packages are always
6
6
welcome. Thanks for your time and involvement.
7
7
8
-
Becoming the maintainer of orphaned packages is
9
-
[easy](#adopting-and-relinquishing-package-maintainership) and very
10
-
welcome.
11
-
12
-
The following lists a few points that help in making the contribution
13
-
process and repository management as smooth and efficient as possible
14
-
for everyone involved.
15
-
16
-
Note that if your have an issue with the opam tool itself this
17
-
should not be filed here but on the opam tool
18
-
[issue tracker](https://github.com/ocaml/opam/issues).
8
+
Table 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)
19
14
20
-
Reporting package installation issues
21
-
-------------------------------------
15
+
Add a new package
16
+
-----------------
22
17
23
-
To report package installation issues:
24
-
25
-
1. First try to search the issue tracker to see if someone already
26
-
reported the issue. If that is the case mention on this issue that
27
-
you are also affected and, if available, add more diagnostic details.
28
-
2. If you create a new issue make sure the issue title mentions the
29
-
package name and the affected version.
30
-
3. Try to give as much information as possible about your setup in
31
-
the issue body:
32
-
1. Add the output of `opam config report`
33
-
2. Add the exact opam invocation and the resulting tool output.
34
-
35
-
Fixing packages
36
-
---------------
37
-
38
-
If you happen to have a fix for a package, please have a look at the
39
-
issue tracker to see if it doesn't concern an existing issue. If that
40
-
is the case mention it in your pull request.
41
-
42
-
Adding new packages
43
-
-------------------
18
+
There are several ways to add a new package to opam-repository.
19
+
You can either use a tool such as `dune-release` or `opam-publish`, or open a PR manually.
20
+
Each ones have their strenghts 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
+
* uploads the documentation
27
+
* creates and uploads a separate archive (also has an option to include the git submodules)
28
+
* works only if your project is on GitHub
29
+
* doesn’t support force-pushed tags
30
+
* `opam-publish` is a more malleable tool focused on publishing. To that end it:
31
+
* works for any type of projects (you can just use a custom archive as an argument)
32
+
* simpler to use than dune-release
33
+
* more focused tool so you should encounter less issues and resistance but it’s more manual
34
+
* only handles the opam linting and publishing
35
+
* you can also open a PR manually:
36
+
* this one gives you the most freedom. It is only recommended for experienced users
37
+
* this is however currently the only way to fix packages (as opposed to adding packages). See the appropriate section below
44
38
45
-
Information about creating new packages and adding them to repository
46
-
is available in
47
-
[opam's manual](https://opam.ocaml.org/doc/Packaging.html).
39
+
We'll cover each ones in the following subsections:
48
40
49
-
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
50
-
make a `hello` package available in opam.ocaml.org.
51
-
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.
41
+
### using dune-release
52
42
53
-
The top-level sources contain the following files with the opam file having the same
54
-
name of the project.
43
+
*if you encounter any issues, please read [dune-release's README](https://github.com/tarides/dune-release/blob/main/README.md)*
55
44
45
+
First, make sure your project is using dune and is hosted on GitHub.
46
+
Then, make sure you’ve forked opam-repository on GitHub. If not go to https://github.com/ocaml/opam-repository/fork
47
+
Then, create a new file in `~/.config/dune/release.yml` with the content as indicated below, change `<username>` by your local username and `<github-user>` by your own github username:
56
48
```
57
-
$ ls hello/
58
-
59
-
src/
60
-
dune
61
-
dune-project
62
-
hello.opam
49
+
remote: git@github.com:<github-username>/opam-repository.git
50
+
local: /home/<username>/.cache/dune/opam-repository/
51
+
```
52
+
Then, you can tag the release using:
53
+
```
54
+
dune-release tag
63
55
```
64
-
65
-
A quick summary of the steps to be followed are listed below:
66
-
56
+
Once done, you can simply call:
67
57
```
68
-
$ dune build
69
-
$ dune-release lint
70
-
$ dune-release tag
71
-
$ dune-release distrib
72
-
$ dune-release publish
73
-
$ dune-release opam pkg
74
-
$ dune-release opam submit
58
+
dune release
75
59
```
60
+
If all goes well this should create the Release on GitHub and open the PR to publish the package on opam-repository.
76
61
77
-
We will now go through each of the above commands in detail:
62
+
For any subsequent releases only the last two steps are necessary.
78
63
79
-
* `dune build`
64
+
### using opam-publish
80
65
81
-
The OCaml source package needs to be built with `dune`, `dune-project`
82
-
and `.opam` files along with the sources. The build should be
83
-
successful before proceeding further. For example:
66
+
*if you encounter any issues, please read [opam-publish's README](https://github.com/ocaml-opam/opam-publish/blob/master/README.md)*
84
67
68
+
Once you have done your release and have an archive available publicly on the internet, simply call:
85
69
```
86
-
$ dune build
87
-
Done: 56/61 (jobs: 1)
70
+
opam-publish <url>
88
71
```
72
+
This will open the PR to publish the package on opam-repository.
89
73
90
-
* `dune-release lint`
74
+
For other options, please refer to `opam-publish --help`
91
75
92
-
The `lint` command checks for the presence of meta files in the
93
-
project folder, and also runs `opam lint`. A sample output is given
94
-
below for your reference:
76
+
### publish manually
95
77
78
+
An opam repository is a tree-like structure of directories and files as follow:
96
79
```
97
-
$ dune-release lint
98
-
[ OK ] File README is present.
99
-
[ OK ] File LICENSE is present.
100
-
[ OK ] File CHANGES is present.
101
-
[ OK ] File opam is present.
102
-
[ OK ] lint opam file hello.opam.
103
-
[ OK ] opam field description is present
104
-
[ OK ] opam fields homepage and dev-repo can be parsed by dune-release
105
-
[ OK ] Skipping doc field linting, no doc field found
106
-
[ OK ] lint /home/guest/hello success
80
+
./
81
+
|- packages/
82
+
|- pkgname/
83
+
| |- pkgname.2.0/
84
+
| |- opam
85
+
|- another-pkgname/
86
+
|- another-pkgname.1.0.0/
87
+
| |- opam
88
+
| |- files/
89
+
| |- fix1.patch
90
+
| |- fix2.patch
91
+
|- another-pkgname.1.0.1/
92
+
|- opam
93
+
|- ...
107
94
```
108
-
109
-
You need to fix any errors reported by linting, and commit the changes
110
-
locally.
111
-
112
-
* `dune-release tag`
113
-
114
-
A ChangeLog `CHANGES` file is required, and the format used is
115
-
available in the
116
-
[dune-release](https://github.com/ocamllabs/dune-release)
117
-
documentation. A minimal example is as follows:
118
-
95
+
So to add a package, simply create a directory with your package name (pkgname) and version
119
96
```
120
-
$ cat CHANGES
121
-
122
-
## v0.0.1 (2021-02-23)
123
-
### Added
124
-
- Meta files for dune release
97
+
mkdir -p packages/pkgname/pkgname.version/
125
98
```
126
-
127
-
After updating the CHANGES file, you need to tag the release. You will
128
-
be prompted to confirm the version, as can be seen in the following
129
-
output:
130
-
99
+
once done, copy the opam file for said package into the newly created directory.
100
+
Edit 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:
131
101
```
132
-
$ dune-release tag
133
-
[-] Extracting tag from first entry in CHANGES
134
-
[-] Using tag "v0.0.1"
135
-
[?] Create git tag v0.0.1 for HEAD? [Y/n]
136
-
Y
137
-
[+] Tagged HEAD with version v0.0.1
102
+
url {
103
+
src: "https://a.publicly-accessible.url/your-archive.tar.gz"
104
+
checksum: [
105
+
"sha256=the-sha256-hash-of-your-archive"
106
+
"sha512=the-sha512-hash-of-your-archive"
107
+
]
108
+
}
138
109
```
110
+
we recommend using more than one checksum and at least sha256 or stronger. Opam currently supports only md5, sha256 and sha512.
139
111
140
-
* `dune-release distrib`
141
-
142
-
The sources are then archived to create a distribution as illustrated
143
-
below:
144
-
112
+
Optionally you might want to integrate files (such as patches) in the repository.
113
+
To do so, create a `files` directory in the directory of your package
114
+
```
115
+
mkdir packages/pkgname/pkgname.version/files/
145
116
```
146
-
$ dune-release distrib
147
-
[-] Building source archive
148
-
[+] Wrote archive _build/hello-v0.0.1.tbz
117
+
then add the files you want to add to this directory. Note that large files are forbidden and the [extra-source](https://opam.ocaml.org/doc/Manual.html#opamsection-extra-sources) section should be used instead.
149
118
150
-
[-] Linting distrib in _build/hello-v0.0.1
151
-
[ OK ] File README is present.
152
-
[ OK ] File LICENSE is present.
153
-
[ OK ] File CHANGES is present.
154
-
[ OK ] File opam is present.
155
-
[ OK ] lint opam file hello.opam.
156
-
[ OK ] opam field description is present
157
-
[ OK ] opam fields homepage and dev-repo can be parsed by dune-release
158
-
[ OK ] Skipping doc field linting, no doc field found
159
-
[ OK ] lint _build/hello-v0.0.1 success
160
-
161
-
[-] Building package in _build/hello-v0.0.1
162
-
Done: 56/60 (jobs: 1)[ OK ] package builds
163
-
164
-
[-] Running package tests in _build/hello-v0.0.1
165
-
Done: 0/0 (jobs: 0)[ OK ] package tests
119
+
Each time you add a file to the `files` directory, you must edit the associated opam file to add the file to the `extra-files` field as follow:
120
+
```
121
+
extra-files: [
122
+
["the-filename" "md5=the-checksum-for-that-file"]
123
+
...
124
+
]
125
+
```
166
126
167
-
[+] Distribution for hello 0.0.1
168
-
[+] Commit c9935ac42271ce23cc422c299c5c3aaf92646499
169
-
[+] Archive _build/hello-v0.0.1.tbz
127
+
Once all that is done, you need to create a new git branch, commit your change, push it to your own fork
170
128
```
129
+
git switch -c release-yourpkg-version
130
+
git add packages/yourpkg/yourpkg.version/
131
+
git commit -pm "Release yourpkg.version"
132
+
git remote add your-github-handle git@github.com:your-github-handle/opam-repository.git
133
+
git push your-github-handle release-yourpkg-version
134
+
```
135
+
and open a PR on opam-repository on GitHub. Congratulation!
171
136
172
-
* `dune-release publish`
137
+
For more technical information about opam files, please read the [opam manual](https://opam.ocaml.org/doc/Manual.html)
173
138
174
-
You can now publish the distribution to your GitHub repository as
175
-
follows:
139
+
Fixing packages
140
+
---------------
176
141
177
-
```
178
-
$ dune-release publish
179
-
[-] Skipping documentation publication for package hello: no doc field in hello.opam
180
-
[-] Publishing distribution
181
-
[-] Publishing to github
182
-
[?] Push tag v0.0.1 to git@github.com:guest/hello? [Y/n]
183
-
Y
184
-
[-] Pushing tag v0.0.1 to git@github.com:guest/hello
185
-
[?] Create release v0.0.1 on git@github.com:guest/hello? [Y/n]
186
-
Y
187
-
[-] Creating release v0.0.1 on git@github.com:guest/hello via github's API
188
-
[+] Succesfully created release with id 38465706
189
-
[?] Upload _build/hello-v0.0.1.tbz as release asset? [Y/n]
190
-
Y
191
-
[-] Uploading _build/hello-v0.0.1.tbz as a release asset for v0.0.1 via github's API
192
-
```
142
+
Packages are fixed as they show up as broken, if the opam-repository maintainers have time.
143
+
If, 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.
193
144
194
-
* `dune-release opam pkg`
145
+
There are several types of fixes:
146
+
* **Changes to the metadata** (e.g. `homepage`, `synopsis`, …) are simple, usualy 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.
195
150
196
-
The .opam file can then be generated using the following command:
151
+
**PSA**: if the PR envisioned is large or involved, please ping the maintainers beforehand.
197
152
198
-
```
199
-
$ dune-release opam pkg
200
-
[-] Creating opam package description for hello
201
-
[+] Wrote opam package description _build/hello.0.0.1/opam
202
-
```
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.
203
154
204
-
* `dune-release opam submit`
155
+
#### Revisions
205
156
206
-
The `~/.config/dune/release.yml` file should then be updated with your
207
-
opam repository settings as indicated below (in particular, change `<username>` by your local username and `<github-user>` by your own github username):
157
+
Revision versions are packages whose version is of the form `<version>-<revision>` with the revision number typically starting at 1.
158
+
They typically privide a slightly modified version of an original release.
208
159
209
-
```
210
-
$ cat ~/.config/dune/release.yml
160
+
For 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 privide a patch to fix something that some people might rely on even if it might be a buggy behivour. 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.
211
161
212
-
user: <username>
213
-
remote: git@github.com:<github-username>/opam-repository.git
214
-
local: /home/<username>/.cache/dune/opam-repository/
215
-
```
162
+
#### Patches
216
163
217
-
You can now submit your package to be included to opam.ocaml.org using
218
-
the following command, which will create a new pull request to
219
-
ocaml/opam-repository:
164
+
To 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 either added through the [extra-source section](https://opam.ocaml.org/doc/Manual.html#opamsection-extra-sources) or the [extra-files field and the files/ subdirectory](https://opam.ocaml.org/doc/Manual.html#opamfield-extra-files) (`extra-source` is preferred to avoid making opam-repository too big).
220
165
221
-
```
222
-
$ dune-release opam submit
223
-
[-] Submitting
224
-
[-] Preparing pull request to ocaml/opam-repository
225
-
[-] Fetching https://github.com/ocaml/opam-repository.git#master
226
-
[-] Checking out a local release-hello-0.0.1 branch
227
-
[-] Pushing release-hello-0.0.1 to git@github.com:guest/opam-repository
228
-
[?] Open PR to ocaml/opam-repository? [Y/n]
229
-
Y
230
-
[-] Opening pull request to merge branch release-hello-0.0.1 of git@github.com:guest/opam-repository into ocaml/opam-repository
231
-
```
166
+
As 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.
232
167
233
-
Congratulations on submitting your first OCaml package!
168
+
As 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.
234
169
235
-
Adopting and relinquishing package maintainership
236
-
-------------------------------------------------
170
+
Governance
171
+
----------
237
172
238
-
Orphaned packages either have no `maintainer:` field or the field is
239
-
set to the repository issue tracker:
173
+
The current points of contact and the full list of maintainers is available in [wiki/Governance](https://github.com/ocaml/opam-repository/wiki/Governance).
174
+
Informations about the infrastructure is available in [wiki/Infrastructure-info](https://github.com/ocaml/opam-repository/wiki/Infrastructure-info).
240
175
241
-
```
242
-
maintainer: "https://github.com/ocaml/opam-repository/issues"
243
-
```
176
+
Typically maintainers gather weekly to discuss ongoing topics, review PRs together and train maintainers in training.
177
+
If 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.
244
178
245
-
If you care about a package and it is orphaned we are keen on having
246
-
you as the maintainer of the package. In order to do so simply issue a
247
-
pull request on the latest version of the package and add your contact
248
-
details in the `maintainer:` field.
249
-
250
-
If it is no longer possible for you to commit to maintain a package
251
-
you can either:
179
+
Policies
180
+
--------
252
181
253
-
1. Try to find a person to replace yourself in that role. Let her
254
-
issue a pull request that updates all the `maintainer:` fields that
255
-
contain your details with her own and do acknowledge the transfer on
256
-
her pull request.
257
-
2. Or, if you cannot find someone to replace you, simply issue a pull
258
-
request that updates all the `maintainer:` fields that have your details
259
-
with the address of the repository issue tracker (see above).
182
+
Maintainers enforce a certain number of policies applied on packages in opam-repository.
183
+
You can read about them in [wiki/Policies](https://github.com/ocaml/opam-repository/wiki/Policies).
260
184
261
-
Other questions
262
-
---------------
185
+
How to deal with CI
186
+
-------------------
263
187
264
-
If your question about contributing is not answered here, please post on the
265
-
<https://discuss.ocaml.org> forum in the `ecosystem` category with your query.
266
-
Beginners questions are welcome there, particularly since we can use your
267
-
question to refine the documentation of the project.
188
+
When you open a PR, a number of checks are done to verify that builds and runs correctly on a number of different platforms.
189
+
You 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).
+2
-12
README.md
+2
-12
README.md
···
1
-
This repository contains OCaml package and compiler metadata and is
2
-
used by the default installation of [opam](https://opam.ocaml.org/).
1
+
This repository contains OCaml package and compiler metadata and is used by the default installation of [opam](https://opam.ocaml.org/).
3
2
4
3
The state of the package ecosystem can be explored using opam-health-check<sup>[[1]]</sup>: http://check.ci.ocaml.org/
5
4
6
-
# CI troubleshooting
7
-
8
-
* If you have an issue or a feature request for opam-CI (used for all PRs), please open a ticket at https://github.com/ocurrent/opam-repo-ci/issues
9
-
* If you think there is an issue in the CI infrastructure, please open a ticket at https://github.com/ocaml/infrastructure/issues
10
-
* If you have an issue or a feature request for opam-health-check, please open a ticket at https://github.com/ocurrent/opam-health-check/issues
11
-
12
5
## How to Contribute
13
6
14
7
Contributions are welcome !
15
8
16
9
The [CONTRIBUTING.md](CONTRIBUTING.md) document has general guidelines
17
-
on how to contribute.
18
-
19
-
If you would like to add a new package consult
20
-
[these instructions](https://opam.ocaml.org/doc/Packaging.html#Publishing).
10
+
on how to contribute and add new packages.
21
11
22
12
## License
23
13