Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add a release checklist #1866

Merged
merged 3 commits into from Oct 4, 2018

Conversation

Projects
None yet
8 participants
@gasche
Copy link
Member

commented Jun 28, 2018

Currently this list isn't publicly available, it sits in various
different versions on @damiendoligez's filesystems. He sent me a copy
when I took care of some of the recent releases. The present
presentation is a result of significant cleanups and changes to the
checklist -- in particular, some mistakes may have jumped in.

This is not a scripted process, it is very informal and it is likely
that there are some mistakes/omissions in the list. Yet, it sounds
better to have it somewhere in the source repository than not have it
around at all. It was certainly helpful to me, and it probably would
be to other release-help volunteers.

(The list is put in tools/ because there isn't a clearly better place
for it. This choice was suggested by Damien.)

@shindere

This comment has been minimized.

Copy link
Contributor

commented Jun 28, 2018

@shindere

This comment has been minimized.

Copy link
Contributor

commented Jun 28, 2018

"Warn Gabriel Scherer (to make a pass on Changes) and OCamlLabs (for OPAM
testing).": I would replace the names by caml-devel@içnria.fr which looks
more stable to me.

The file skips from step "1: check repository state" to step
"3: build, refresh dependencies, sanity
checks": step 2 is missing.

"check that .depend files have no absolute path in them": well, if one day
we have a global .depend there will be slashes in it, although paths are not
absolute.

./tools/check-symbol-names asmrun/.a byterun/.a

should now be:

./tools/check-symbol-names runtime/*.a

"# must have empty output and result 0": I'd replace result by return

"at this point, VERSION contains N+devD": I think here you are referring to
the VERSION file at the root of the repository but it is ambiguous because
you have introduced a VERSION environemnt variable earlier so I'd say "the
VERSION file (at the root of the repository)" or something clearer.

About the OPAM part: for the non-expert I am, I don't understand the
instructions. In which directories should the mentionned commands be run?

Why do the compression commands (gzip and xz) use time?

"## 8: upload the archive and compute checksums": archives rather than
archive?

About OS X packaging: the package-macosx target is no longer available.

For production releases, you should get in touch with ocaml.org to
organize the webpage for the new release. See

<https://github.com/ocaml/ocaml.org/issues/819>

This comment has been minimized.

Copy link
@pmetzger

pmetzger Jun 28, 2018

Member

We need a bit more on the list than this, I think, because for 4.06 the web pages were not fixed for quite some time and not everything was noticed at once.

This comment has been minimized.

Copy link
@gasche

gasche Jun 28, 2018

Author Member

In the issue someone volunteered to write more detailed steps, and I'm waiting for them to include here. ;-)

Happy hacking,

-- Damien Doligez for the OCaml team.
```

This comment has been minimized.

Copy link
@pmetzger

pmetzger Jun 28, 2018

Member

Missing a trailing carriage return.

@pmetzger

This comment has been minimized.

Copy link
Member

commented Jun 28, 2018

This is a very good list! Thank you!

For MacOS, it would be good to also inform the people who manage the Brew formula for OCaml (I don't know who that is) and to inform the MacPorts maintainer (which is me.)

@xavierleroy

This comment has been minimized.

Copy link
Contributor

commented Jun 28, 2018

I'm slightly uncomfortable at the quantity of information about our server infrastructure that is made public here. But I guess the cat is out of the bag already...

@pmetzger

This comment has been minimized.

Copy link
Member

commented Jun 28, 2018

I'm slightly uncomfortable at the quantity of information about our server infrastructure that is made public here.

It could be removed from the file still. Not that many people have seen it.

@gasche gasche force-pushed the gasche:release-checklist branch from 11ebacc to 03c3766 Jun 28, 2018

@gasche

This comment has been minimized.

Copy link
Member Author

commented Jun 28, 2018

I removed details from the file. I'm not fully satisfied without a reasonable place to store the remaining bits (right now they are on my machine and Damien's, we should think of something more portable), but that's a good compromise I guess.

@avsm

This comment has been minimized.

Copy link
Member

commented Jun 29, 2018

As we open up the opam hardware infrastructure to more developers (especially non-x86), I wanted a place to store server details in a slightly less public place. I could create a private repository along the lines of https://github.com/ocaml/infrastructure-private (to go with the public https://github.com/ocaml/infrastructure)

@shindere

This comment has been minimized.

Copy link
Contributor

commented Jun 29, 2018

Before I forget: hadn't we decided to change the executable magic number for
each production release?

Shouldn't that be mentionned / explained in the list?

@dra27
Copy link
Contributor

left a comment

Since #1148 will be merged soon, I've done a scan of non-rebase-requiring PRs for check-typo so that we don't merge things which then break Travis/Inria's trunk run.

This file definitely wants ocaml-typo=missing-header in .gitattributes and probably long-line as well.

# for actual releases: check and change the Changes header
# (remove "next version" and add a date)
git add VERSION
git commit -m "last commit before tagging $VERSION"

This comment has been minimized.

Copy link
@dra27

dra27 Jun 30, 2018

Contributor

Whitespace at end of line


```
ssh <<archive machine>> "mkdir -p $DIST/notes"
scp INSTALL.adoc LICENSE README.adoc README.win32.adoc Changes <<archive machine>>:$DIST/notes/

This comment has been minimized.

Copy link
@dra27

dra27 Jun 30, 2018

Contributor

This line is over-long (though perhaps that just means ocaml-typo=long-line is wanted in .gitattributes for this file)

Happy hacking,

-- Damien Doligez for the OCaml team.

This comment has been minimized.

Copy link
@dra27

dra27 Jun 30, 2018

Contributor

Stray whitespace here

@shindere

This comment has been minimized.

Copy link
Contributor

commented Jul 2, 2018

@dra27

This comment has been minimized.

Copy link
Contributor

commented Jul 2, 2018

@shindere - it's line 188, so it could be altered. URLs already can't cause long-line to trigger (IIRC the rule is that if the line is only over-long because of one URL then long-line is suppressed - i.e. you should still be trying to keep to 80 characters if possible!)

@gasche

This comment has been minimized.

Copy link
Member Author

commented Jul 2, 2018

Thanks for all the feedback. I will do another turn of the crank at some point. I plan to only fix the minor issues, though, not add new content to the file. It will remain imperfect, and we can improve it gradually.

I also need to get confirmation by @damiendoligez that the reordering of steps (compared to the initial spaghetti file) is valid, but I may have to go get it in person. It's hard to spend time on release files outside releases, and we have other things to do during the release.

@shindere

This comment has been minimized.

Copy link
Contributor

commented Jul 2, 2018

@shindere

This comment has been minimized.

Copy link
Contributor

commented Jul 2, 2018

@damiendoligez
Copy link
Member

left a comment

A few small things. The order of steps looks OK.

# at this point, VERSION contains N+devD
# increment VERSION into N+dev(D+1); for example,
# 4.07.0+dev8-2018-06-19 => 4.07.0+dev9-2018-06-26
# for actual releases: check and change the Changes header

This comment has been minimized.

Copy link
@damiendoligez

damiendoligez Jul 2, 2018

Member

"actual releases" should be "production releases"

git commit -m "change VERSION for $VERSION" -a
git tag -m "release $VERSION" $VERSION

# for actual releases, change VERSION into (N+1)+dev0; for example,

This comment has been minimized.

Copy link
@damiendoligez

damiendoligez Jul 2, 2018

Member

Again, this should be "production releases".


# for actual releases, change VERSION into (N+1)+dev0; for example,
# 4.08.0 => 4.08.1+dev0
# for release candidates, use N+dev(D+1) instead; for example,

This comment has been minimized.

Copy link
@damiendoligez

damiendoligez Jul 2, 2018

Member

And this should be "testing releases".


## 13: update Mantis

Update Mantis by adding $MAJOR.$MINR.$BUGFIX as a version number for reports.

This comment has been minimized.

Copy link
@damiendoligez

damiendoligez Jul 2, 2018

Member

$MINR is missing an O


Update Mantis by adding $MAJOR.$MINR.$BUGFIX as a version number for reports.

## 14: build and release OSX binaries

This comment has been minimized.

Copy link
@damiendoligez

damiendoligez Jul 2, 2018

Member

As @shindere said, this whole section is dead code.

This comment has been minimized.

Copy link
@gasche

gasche Jul 2, 2018

Author Member

Well there goes my mild guilt at ignoring it each time...


See the email announce templates at the end of this file.

## 13: update Mantis

This comment has been minimized.

Copy link
@damiendoligez

damiendoligez Jul 2, 2018

Member

You should probably swap steps 12 and 13.

@gasche

This comment has been minimized.

Copy link
Member Author

commented Jul 2, 2018

Thanks! Speaking of "update Mantis", I have never done it myself, I don't think I have the necessary rights, and I don't know how to do it; if you have an URL at hand to cut the link chase, I could include it in the notes.

@damiendoligez

This comment has been minimized.

Copy link
Member

commented Jul 3, 2018

You would go to https://caml.inria.fr/mantis/manage_proj_edit_page.php?project_id=1 , log in, then scroll down to "Versions".

@gasche

This comment has been minimized.

Copy link
Member Author

commented Jul 3, 2018

Thanks! I can confirm that I don't have the privilege level to do it.

@gasche gasche force-pushed the gasche:release-checklist branch from 03c3766 to ee98bb0 Jul 3, 2018

@gasche gasche force-pushed the gasche:release-checklist branch from ee98bb0 to 28566ef Jul 3, 2018

@gasche

This comment has been minimized.

Copy link
Member Author

commented Jul 3, 2018

Thanks to everyone's careful feedback, I did another pass on the file, and I believe that all concerns voiced so far have been addressed.

In particular, I followed @shindere's excellent suggestion to include a remark on bumping magic numbers (I was glad to add a section 2 instead of having to manually renumber). Instead of giving too much details in that file, I created a utils/HACKING.adoc file with a description of the magic number bumping policy.

@dra27: I was perplexed for a while by the fact that ./tools/check-typo utils/HACKING.adoc would return a missing-header error despite *.adoc being covered in .gitattributes. Then I noticed that I had forgotten to git add the file; my understanding is that it is then not taken into account by whatever gitattributes-querying mechanism that you are using. Could you maybe have check-typo emit a warning when interrogated on a file that is not part of the git index? (It doesn't need to be a scary warning, as it is a reasonable use-case during development of a new file, but still it would have helped me.)

@dra27

This comment has been minimized.

Copy link
Contributor

commented Jul 3, 2018

@gasche - indeed, the problem is that git check-attr doesn’t apply to files not in git, or at least registered in the index (I think if you had done git add -N it would also have been fine).

I’ll see if there’s a way to get hypothetical Git attributes for non-added files, but otherwise your idea of a warning is good.

@pmetzger

This comment has been minimized.

Copy link
Member

commented Jul 3, 2018

I think it would be wise to have a step, about a week before release, notifying maintainers for various packaging organizations (like Debian or Arch or Brew or what have you) that they should check that the last release candidate works okay on their platform in preparation for release. It might be a bit late in the 4.07 process for that, but it could be done for 4.08.

@shindere

This comment has been minimized.

Copy link
Contributor

commented Jul 3, 2018

@pmetzger

This comment has been minimized.

Copy link
Member

commented Jul 3, 2018

utils/ is a source directory. I'm not too happy about putting documentation there.

I think HACKING style files are a bit different, though. They are not information about using the code, but rather guides to the code itself.

@gasche

This comment has been minimized.

Copy link
Member Author

commented Jul 3, 2018

@pmetzger: my expectation is that distribution maintainers would follow caml-list or caml-announce, and thus be notified of release candidates which generally happen about one week before the release. Do we really need a separate communication step?

@xavierleroy: we already have HACKING.adoc files in parsing/ and typing/. I generally like having developer-oriented documentation close to the thing they are documenting.

@shindere

This comment has been minimized.

Copy link
Contributor

commented Jul 3, 2018

@pmetzger

This comment has been minimized.

Copy link
Member

commented Jul 3, 2018

@gasche:

my expectation is that distribution maintainers would follow caml-list or caml-announce, and thus be notified of release candidates which generally happen about one week before the release. Do we really need a separate communication step?

Yes, you're probably right that it is unnecessary. That said, I would also announce release candidates on discuss.ocaml.org, just in case.

@damiendoligez
Copy link
Member

left a comment

A few suggestions from testing the checklist on 4.07.0.

export VERSION=$MAJOR.$MINOR.$BUGFIX$PLUSEXT

export REPO=http://github.com/ocaml/ocaml
export DIST=<<dist path>>/ocaml/ocaml-$MAJOR.$MINOR

This comment has been minimized.

Copy link
@damiendoligez

damiendoligez Jul 10, 2018

Member

Why invent a new notation for metavariables where a plain variable does the job better? If you just write $DIST_PATH instead of <<dist path>> this file will be easier to use by the release manager.

# ocamldoc/stdlib_non_prefixed depends on 'world'

# check that .depend files have no absolute path in them
find . -name .depend | xargs grep ' /'

This comment has been minimized.

Copy link
@damiendoligez

damiendoligez Jul 10, 2018

Member

Please add a comment # must have empty output.

# 4.07.0+dev8-2018-06-19 => 4.07.0+dev9-2018-06-26
# for production releases: check and change the Changes header
# (remove "next version" and add a date)
git add VERSION

This comment has been minimized.

Copy link
@damiendoligez

damiendoligez Jul 10, 2018

Member

Should be git add VERSION Changes since the Changes file may be changed at this point.


```
# copy foo+rc1+... switches into foo+rc2+...
for f in *+rc1*; do mkdir -p $f $(echo $f | sed 's/+rc1/+rc2/g'); done

This comment has been minimized.

Copy link
@damiendoligez

damiendoligez Jul 10, 2018

Member

I don't think you need the $f argument to mkdir.

# copy foo+rc1+... switches into foo+rc2+...
for f in *+rc1*; do mkdir -p $f $(echo $f | sed 's/+rc1/+rc2/g'); done
for f in *+rc1*/*; do cp $f $(echo $f | sed 's/+rc1/+rc2/g'); done
git add *+rc2* # import into git (the files still use +rc1 all over)

This comment has been minimized.

Copy link
@damiendoligez

damiendoligez Jul 10, 2018

Member

This line doesn't work for a production release.


# upload manual checksums
ssh <<archive machine>> "cd $DIST; md5sum ocaml-$BRANCH-refman* >>MD5SUM"
ssh <<archive machine>> "cd $DIST; sha256sum ocaml-$BRANCH-refman* >>SHA512SUM"

This comment has been minimized.

Copy link
@damiendoligez

damiendoligez Jul 10, 2018

Member

Should be sha512sum.

mkdir -p ocaml-$BRANCH
cd ocaml-$BRANCH
wget http://caml.inria.fr/pub/distrib/ocaml-$BRANCH/ocaml-$BRANCH-refman-html.tar.gz
tar -xzvf manual-ocaml-$BRANCH-refman-html.tar.gz # this extracts into htmlman/

This comment has been minimized.

Copy link
@damiendoligez

damiendoligez Jul 10, 2018

Member

remove the extraneous manual-

mv htmlman/* -t . # move HTML content to docs/manual-caml-$BRANCH
rmdir htmlman

cd <<www>>/caml/pub/docs/manual-ocaml

This comment has been minimized.

Copy link
@damiendoligez

damiendoligez Jul 10, 2018

Member

Remove the last part (manual-ocaml).


We say that we "bump" a magic number when we update its version part
in config.mlp. To bump all magic numbers is to increment the version
of all kinds of magic numbers.

This comment has been minimized.

Copy link
@damiendoligez

damiendoligez Jul 10, 2018

Member

You should write "every kind", as "all kinds of" has another meaning in English.


This should preferably be done just before the first testing release
(the first beta, or the first rc if there is no beta) of the new major
release. We want to to happen after all format-breaking changes have

This comment has been minimized.

Copy link
@damiendoligez

damiendoligez Jul 10, 2018

Member

"we want to to" -> "we want it to"

@gasche gasche force-pushed the gasche:release-checklist branch from 28566ef to 046c7a6 Jul 13, 2018

@gasche

This comment has been minimized.

Copy link
Member Author

commented Jul 13, 2018

@damiendoligez thanks, I made another pass of changes.

(The opam scripts still don't work in the edge cases of creating a new directory or the +trunk stuff, but this may have to suffice for now.)

@gasche gasche force-pushed the gasche:release-checklist branch from 046c7a6 to 6461790 Jul 14, 2018

@dra27

This comment has been minimized.

Copy link
Contributor

commented Jul 16, 2018

Some notes for opam 2.0.0 packages:

  • The next trunk version of the ocaml meta package has to be created when the new release is branched. So, for example, when 4.07 was branched, the ocaml.4.08.0 package became necessary (see ocaml/opam-repository@fa33588).
  • The changes presently made to compilers in OPAM 1.2.2 get made to the ocaml-base-compiler package. This is very easy at release, as the beta and rc definitions will already have been in ocaml-variants, so they just copied and the version number updated.
  • Since homebrew will upgrade about 3 seconds after the release, it's important to create an ocaml-system package for the new release (see ocaml/opam-repository#12357)

@dra27 dra27 dismissed their stale review Jul 16, 2018

check-typo dealt with

@pmetzger

This comment has been minimized.

Copy link
Member

commented Jul 16, 2018

A suggestion: in the few weeks before a release, some effort should be made to make sure that the most commonly installed third party packages (say things like menhir and utop and lwt and the like) have opam packages compatible with the new release. This shouldn't be a blocking step, but it would be good to make a best-efforts attempt.

@gasche

This comment has been minimized.

Copy link
Member Author

commented Jul 16, 2018

I already gave an opinion on this topic on the relevant Discuss thread: I think this is outside the responsibility of the core compiler team, and in any case while that may be part of the decision in the timing of a release, it needs not be part of the compiler release process.

@gasche gasche force-pushed the gasche:release-checklist branch from 6461790 to 51fb944 Jul 16, 2018

@gasche gasche force-pushed the gasche:release-checklist branch from 51fb944 to 8a2d2ab Aug 19, 2018

@gasche

This comment has been minimized.

Copy link
Member Author

commented Aug 19, 2018

I just rebased the PR on trunk and fixed all pending comments.

(@dra27, I didn't include the opam2 instructions, sorry. Hopefully this can come as a separate PR after this one is merged.)

@gasche

This comment has been minimized.

Copy link
Member Author

commented Aug 19, 2018

(No one has seemed interested in deciding to approve it, yet that would be necessary for it to be merged.)

@shindere

This comment has been minimized.

Copy link
Contributor

commented Aug 19, 2018

@dbuenzli

This comment has been minimized.

Copy link
Contributor

commented Aug 20, 2018

Not a prerequisite for merge but if the ocaml-manual opam package could be updated in the process that would be nice.

(Even better would be to install the manual, Changes and README file in the opam var ocaml:doc directory when the ocaml package is installed. This allows users to simply odig changes ocaml to get the release notes of their current opam compiler version without having to track them down on the interweb).

@shindere

This comment has been minimized.

Copy link
Contributor

commented Aug 20, 2018

@shindere

This comment has been minimized.

Copy link
Contributor

commented Oct 3, 2018

Thanks, @damiendoligez

@damiendoligez damiendoligez force-pushed the gasche:release-checklist branch from 084aeac to 28c299a Oct 4, 2018

gasche and others added some commits Jun 28, 2018

add a release checklist
Currently this list isn't publicly available, it sits in various
different versions on @damiendoligez's filesystems. He sent me a copy
when I took care of some of the recent releases. The present
presentation is a result of significant cleanups and changes to the
checklist -- in particular, some mistakes may have jumped in.

This is not a scripted process, it is very informal and it is likely
that there are some mistakes/omissions in the list. Yet, it sounds
better to have it somewhere in the source repository than not have it
around at all. It was certainly helpful to me, and it probably would
be to other release-help volunteers.

(The list is put in tools/ because there isn't a clearly better place
for it. This choice was suggested by Damien.)

@damiendoligez damiendoligez force-pushed the gasche:release-checklist branch from 28c299a to a45f605 Oct 4, 2018

@damiendoligez

This comment has been minimized.

Copy link
Member

commented Oct 4, 2018

Added a few fixes after trying it out on 4.07.1+rc1, made changes to take @shindere's remarks into account, and rebased.
I'll merge after CI gives the green light.

@damiendoligez damiendoligez merged commit ecd5275 into ocaml:trunk Oct 4, 2018

2 checks passed

continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details

damiendoligez added a commit to damiendoligez/ocaml that referenced this pull request Nov 5, 2018

add a release checklist (ocaml#1866)
* add a release checklist

Currently this list isn't publicly available, it sits in various
different versions on @damiendoligez's filesystems. He sent me a copy
when I took care of some of the recent releases. The present
presentation is a result of significant cleanups and changes to the
checklist -- in particular, some mistakes may have jumped in.

This is not a scripted process, it is very informal and it is likely
that there are some mistakes/omissions in the list. Yet, it sounds
better to have it somewhere in the source repository than not have it
around at all. It was certainly helpful to me, and it probably would
be to other release-help volunteers.

(The list is put in tools/ because there isn't a clearly better place
for it. This choice was suggested by Damien.)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.