package / ocaml-base-compiler.4.10.0 / tools / release-checklist
1 These are informal notes on how to do an OCaml release.
2
3 Following these steps requires commit right in the OCaml repository,
4 as well as SSH access to the inria.fr file servers hosting the
5 distribution archives and manual.
6
7 We are not fully confident that those steps are correct, feel free to
8 check with other release managers in case of doubt.
9
10 Note: we say that a new release is a "testing release" if it is a Beta
11 version or Release Candidate. Otherwise, we call it a "production
12 release".
13
14
15 ## A few days in advance
16
17 Send a mail on caml-devel to warn Gabriel (to make a pass on Changes)
18 and the OCamlLabs folks (for OPAM testing).
19
20 ## 0: release environment setup
21
22 ```
23 rm -f /tmp/env-$USER.sh
24 cat >/tmp/env-$USER.sh <<EOF
25
26 export MAJOR=4
27 export MINOR=08
28 export BUGFIX=0
29 export PLUSEXT=
30
31 export WORKTREE=~/o/\$MAJOR.\$MINOR
32 # must be the git worktree for the branch you are releasing
33
34 export BRANCH=\$MAJOR.\$MINOR
35 export VERSION=\$MAJOR.\$MINOR.\$BUGFIX\$PLUSEXT
36
37 export REPO=http://github.com/ocaml/ocaml
38
39 # these values are specific to caml.inria's host setup
40 # they are defined in the release manager's .bashrc file
41 export ARCHIVE_HOST="$OCAML_RELEASE_ARCHIVE_HOST"
42 export ARCHIVE_PATH="$OCAML_RELEASE_ARCHIVE_PATH"
43 export WEB_HOST="$OCAML_RELEASE_WEB_HOST"
44 export WEB_PATH="$OCAML_RELEASE_WEB_PATH"
45
46 export DIST="\$ARCHIVE_PATH/ocaml/ocaml-\$MAJOR.\$MINOR"
47 EOF
48 source /tmp/env-$USER.sh
49 echo $VERSION
50 ```
51
52
53 ## 1: check repository state
54
55 ```
56 cd $WORKTREE
57 git status # check that the local repo is in a clean state
58 git pull
59 ```
60
61 ## 2: magic numbers
62
63 If you are about to do a major release, you should check that the
64 magic numbers have been updated since the last major release. It is
65 preferable to do this just before the first testing release for this
66 major version, typically the first beta.
67
68 See the HACKING file of `utils/` for documentation on how to bump the
69 magic numbers.
70
71 ## 3: build, refresh dependencies, sanity checks
72
73 ```
74 make distclean
75 git clean -n -d -f -x # Check that "make distclean" removed everything
76
77 INSTDIR=/tmp/ocaml-${VERSION}
78 rm -rf ${INSTDIR}
79 ./configure -prefix ${INSTDIR}
80
81 make -j5
82 make alldepend
83
84 # check that .depend files have no absolute path in them
85 find . -name .depend | xargs grep ' /'
86 # must have empty output
87
88 make install
89 ./tools/check-symbol-names runtime/*.a
90 # must have empty output and return 0
91 ```
92
93
94 ## 4: tests
95
96 ```
97 make tests
98 ```
99
100
101 ## 5: build, tag and push the new release
102
103 ```
104 # at this point, the VERSION file contains N+devD
105 # increment it into N+dev(D+1); for example,
106 # 4.07.0+dev8-2018-06-19 => 4.07.0+dev9-2018-06-26
107 # for production releases: check and change the Changes header
108 # (remove "next version" and add a date)
109 ./autogen
110 git commit -a -m "last commit before tagging $VERSION"
111
112 # update VERSION with the new release; for example,
113 # 4.07.0+dev9-2018-06-26 => 4.07.0+rc2
114 # Update ocaml-variants.opam with new version.
115 # Update \year in manual/manual/macros.hva
116 rm -r autom4te.cache
117 ./autogen
118 make coreboot -j5
119 make coreboot -j5 # must say "Fixpoint reached, bootstrap succeeded."
120 git commit -m "release $VERSION" -a
121 git tag -m "release $VERSION" $VERSION
122
123 # for production releases, change the VERSION file into (N+1)+dev0; for example,
124 # 4.08.0 => 4.08.1+dev0
125 # for testing candidates, use N+dev(D+2) instead; for example,
126 # 4.07.0+rc2 => 4.07.0+dev10-2018-06-26
127 # Revert ocaml-variants.opam to its "trunk" version.
128 rm -r autom4te.cache
129 ./autogen
130 git commit -m "increment version number after tagging $VERSION" VERSION configure ocaml-variants.opam
131 git push
132 git push --tags
133 ```
134
135 ## 5.1: create the release on github (only for a production release)
136
137 open https://github.com/ocaml/ocaml/releases
138 # and click "Draft a new release"
139 # for a minor release, the description is:
140 Bug fixes. See [detailed list of changes](https://github.com/ocaml/ocaml/blob/$MAJOR.$MINOR/Changes).
141
142
143 ## 6: create OPAM packages
144
145 Create ocaml-variants packages for the new version, copying the particular
146 switch configuration choices from the previous version.
147
148 Do not forget to add/update the checksum field for the tarballs in the
149 "url" section of the opam files. Use opam-lint before sending the pull
150 request.
151
152 ## 7: build the release archives
153
154 ```
155 cd $WORKTREE
156 TMPDIR=/tmp/ocaml-release
157 git checkout $VERSION
158 git checkout-index -a -f --prefix=$TMPDIR/ocaml-$VERSION/
159 cd $TMPDIR
160 gtar -c --owner 0 --group 0 -f ocaml-$VERSION.tar ocaml-$VERSION
161 gzip -9 <ocaml-$VERSION.tar >ocaml-$VERSION.tar.gz
162 xz <ocaml-$VERSION.tar >ocaml-$VERSION.tar.xz
163 ```
164
165
166 ## 8: upload the archives and compute checksums
167
168 For the first beta of a major version, create the distribution directory on
169 the server:
170 ```
171 ssh $ARCHIVE_HOST "mkdir -p $DIST"
172 ```
173
174 Upload the archives:
175 ```
176 scp ocaml-$VERSION.tar.{xz,gz} $ARCHIVE_HOST:$DIST
177 ```
178
179 To update the checksum files on the remote host, we first upload the
180 release environment.
181 (note: this assumes the user name is the same on the two machines)
182
183 ```
184 scp /tmp/env-$USER.sh $ARCHIVE_HOST:/tmp/env-$USER.sh
185 ```
186
187 and then login there to update the checksums (MD5SUM, SHA512SUM)
188
189 ```
190 ssh $ARCHIVE_HOST
191 source /tmp/env-$USER.sh
192 cd $DIST
193
194 cp MD5SUM MD5SUM.old
195 md5sum ocaml-$VERSION.tar.{xz,gz} > new-md5s
196 # check new-md5s to ensure that they look right, and then
197 cat new-md5s >> MD5SUM
198 # if everything worked well,
199 rm MD5SUM.old new-md5s
200
201 # same thing for SHA512
202 cp SHA512SUM SHA512SUM.old
203 sha512sum ocaml-$VERSION.tar.{xz,gz} > new-sha512s
204 cat new-sha512s >> SHA512SUM
205 rm SHA512SUM.old new-sha512s
206
207 # clean up
208 rm /tmp/env-$USER.sh
209 exit
210 ```
211
212
213 ## 9: update note files (technical documentation)
214
215 ```
216 ssh $ARCHIVE_HOST "mkdir -p $DIST/notes"
217 cd ocaml-$VERSION
218 scp INSTALL.adoc LICENSE README.adoc README.win32.adoc Changes \
219 $ARCHIVE_HOST:$DIST/notes/
220 ```
221
222
223 ## 10: upload the reference manual
224
225 You don't need to do this if the previous release had the same
226 $MAJOR.$MINOR ($BRANCH) value and the exact same manual -- this is frequent if
227 it was a release candidate.
228
229 ```
230 cd $WORKTREE
231 make
232 make install
233 export PATH="$INSTDIR/bin:$PATH"
234 cd manual
235 make clean
236 make
237 rm -rf /tmp/release
238 mkdir -p /tmp/release
239 RELEASENAME="ocaml-$BRANCH-"
240 make -C manual release RELEASE=/tmp/release/$RELEASENAME
241 scp /tmp/release/* $ARCHIVE_HOST:$DIST/
242
243
244 # upload manual checksums
245 ssh $ARCHIVE_HOST "cd $DIST; md5sum ocaml-$BRANCH-refman* >>MD5SUM"
246 ssh $ARCHIVE_HOST "cd $DIST; sha512sum ocaml-$BRANCH-refman* >>SHA512SUM"
247 ```
248
249 Releasing the manual online happens on another machine:
250 Do this ONLY FOR A PRODUCTION RELEASE
251
252 ```
253 scp /tmp/env-$USER.sh $ARCHIVE_HOST:/tmp/env-$USER.sh
254 ssh $ARCHIVE_HOST
255 source /tmp/env-$USER.sh
256 scp /tmp/env-$USER.sh $WEB_HOST:/tmp
257 ssh $WEB_HOST
258 source /tmp/env-$USER.sh
259
260 cd $WEB_PATH/caml/pub/docs
261 mkdir -p manual-ocaml-$BRANCH
262 cd manual-ocaml-$BRANCH
263 rm -fR htmlman ocaml-$BRANCH-refman-html.tar.gz
264 wget http://caml.inria.fr/pub/distrib/ocaml-$BRANCH/ocaml-$BRANCH-refman-html.tar.gz
265 tar -xzvf ocaml-$BRANCH-refman-html.tar.gz # this extracts into htmlman/
266 /bin/cp -r htmlman/* . # move HTML content to docs/manual-caml-$BRANCH
267 rm -fR htmlman ocaml-$BRANCH-refman-html.tar.gz
268
269 cd $WEB_PATH/caml/pub/docs
270 rm manual-ocaml
271 ln -sf manual-ocaml-$BRANCH manual-ocaml
272 ```
273
274
275 ## 11: prepare web announce for the release
276
277 For production releases, you should get in touch with ocaml.org to
278 organize the webpage for the new release. See
279
280 <https://github.com/ocaml/ocaml.org/issues/819>
281
282
283 ## 13: announce the release on caml-list and caml-announce
284
285 See the email announce templates at the end of this file.
286
287
288
289 # Announces
290
291 ## Announcing a production release:
292
293 ```
294 Dear OCaml users,
295
296 We have the pleasure of celebrating <event> by announcing the release of
297 OCaml version $VERSION.
298 This is mainly a bug-fix release, see the list of changes below.
299
300 It is (or soon will be) available as a set of OPAM switches,
301 and as a source download here:
302 https://caml.inria.fr/pub/distrib/ocaml-$BRANCH/
303
304 Happy hacking,
305
306 -- Damien Doligez for the OCaml team.
307
308 << insert the relevant Changes section >>
309 ```
310
311 ## Announcing a release candidate:
312
313 ```
314 Dear OCaml users,
315
316 The release of OCaml version $MAJOR.$MINOR.$BUGFIX is imminent. We have
317 created a release candidate that you can test.
318
319 The source code is available at these addresses:
320
321 https://github.com/ocaml/ocaml/archive/$VERSION.tar.gz
322 https://caml.inria.fr/pub/distrib/ocaml-$BRANCH/ocaml-$VERSION.tar.gz
323
324 The compiler can also be installed as an OPAM switch with one of the
325 following commands.
326
327 opam switch create ocaml-variants.$VERSION --repositories=default,beta=git+https://github.com/ocaml/ocaml-beta-repository.git
328
329 or
330
331 opam switch create ocaml-variants.$VERSION+<VARIANT> --repositories=default,beta=git+https://github.com/ocaml/ocaml-beta-repository.git
332
333 where you replace <VARIANT> with one of these:
334 afl
335 default-unsafe-string
336 force-safe-string
337 flambda
338 fp
339 fp+flambda
340
341 We want to know about all bugs. Please report them here:
342 https://github.com/ocaml/ocaml/issues
343
344 Happy hacking,
345
346 -- Damien Doligez for the OCaml team.
347
348 << insert the relevant Changes section >>
349 ```
350
351 ## Announcing a beta version:
352
353 ```
354 Dear OCaml users,
355
356 The release of OCaml $MAJOR.$MINOR.$BUGFIX is approaching. We have created
357 a beta version to help you adapt your software to the new features
358 ahead of the release.
359
360 The source code is available at these addresses:
361
362 https://github.com/ocaml/ocaml/archive/$VERSION.tar.gz
363 https://caml.inria.fr/pub/distrib/ocaml-$BRANCH/$VERSION.tar.gz
364
365 The compiler can also be installed as an OPAM switch with one of the
366 following commands.
367
368 opam switch create ocaml-variants.$VERSION --repositories=default,beta=git+https://github.com/ocaml/ocaml-beta-repository.git
369
370 or
371
372 opam switch create ocaml-variants.$VERSION+<VARIANT> --repositories=default,beta=git+https://github.com/ocaml/ocaml-beta-repository.git
373
374 where you replace <VARIANT> with one of these:
375 afl
376 default-unsafe-string
377 force-safe-string
378 flambda
379 fp
380 fp+flambda
381
382 We want to know about all bugs. Please report them here:
383 https://github.com/ocaml/ocaml/issues
384
385 Happy hacking,
386
387 -- Damien Doligez for the OCaml team.
388 ```
389