this repo has no description
Merge pull request #25963 from hannesm/contributing-extra-source
revise contributing to specify extra-source instead of extra-files
authored by
Marcello Seri
and committed by
GitHub
fa73269c
0b9453aa
+15
-14
+15
-14
CONTRIBUTING.md
+15
-14
CONTRIBUTING.md
···
85
85
|- another-pkgname/
86
86
|- another-pkgname.1.0.0/
87
87
| |- opam
88
-
| |- files/
89
-
| |- fix1.patch
90
-
| |- fix2.patch
91
88
|- another-pkgname.1.0.1/
92
89
|- opam
93
90
|- ...
···
109
106
```
110
107
we recommend using more than one checksum and at least sha256 or stronger. Opam currently supports only md5, sha256 and sha512.
111
108
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
109
+
Optionally 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.
110
+
111
+
Add 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:
114
112
```
115
-
mkdir packages/pkgname/pkgname.version/files/
113
+
extra-source "the-filename" {
114
+
src: "https://my-server/my-file"
115
+
checksum: [
116
+
"sha256=the-checksum-for-my-file"
117
+
]
118
+
}
116
119
```
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.
118
120
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:
121
+
If 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:
120
122
```
121
-
extra-files: [
122
-
["the-filename" "md5=the-checksum-for-that-file"]
123
-
...
124
-
]
123
+
patches: [ "the-filename" ]
125
124
```
126
125
127
-
Once all that is done, you need to create a new git branch, commit your change, push it to your own fork
126
+
If 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.
127
+
128
+
Once all that is done, you need to create a new git branch, commit your change, push it to your own fork
128
129
```
129
130
git switch -c release-yourpkg-version
130
131
git add packages/yourpkg/yourpkg.version/
···
161
162
162
163
#### Patches
163
164
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).
165
+
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 added through the [extra-source section](https://opam.ocaml.org/doc/Manual.html#opamsection-extra-sources).
165
166
166
167
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.
167
168