Skip to content

Making a release

Jump to bottom
Mikolaj Konarski edited this page May 25, 2022 · 334 revisions

Release checklist

Cabal

  • make sure cabal-version of Cabal and Cabal-syntax is within the backwards compat range (and not too ancient, either).
  • bump copyright years everywhere on branch master so that it doesn't have to be repeated on each branch
  • review tickets labelled with the release number or with that milestone or in a relevant release project; review&merge anything there, bump the others to the future release
  • Add the new SPDX License List data
  • bump Cabal version to the desired release (or pre-release) version in all relevant *.cabal files (and deps versions on cabal packages; also verify hackage-security and other tools have proper cabal deps versions)
  • in setup-depends of `cabal-testsuite/cabal-testsuite.cabal, apparently the version needs to be the previous major version of cabal or else exceptions are thrown (Custom setup fun)
  • bump version in .gitlab-ci.yml, Cabal/Makefile and doc/conf.py
  • update Cabal/ChangeLog.md and release-notes/Cabal-x.x.x.x.md using changelog-d and PR log obtained with something like git log Cabal-v3.6.3.0..3.8 (TODO: but this does not exclude changelogs that are already in old release notes; should we remove them manually after inclusion?) (TODO: should we use the --short or the --long mode? old release notes seem to mix those; I went for --long for this release) (TODO: where to put Cabal-syntax and cabal-install-solver PR changelogs? For now, I'm adding them to Cabal and cabal-install changelogs, respectively, but it's a manual process)
  • if this is the first major version release, bump master branch to the next odd version
  • copy changelog and release notes to master branch
  • cabal check in all relevant directories
  • cabal sdist
  • upload candidate for Cabal-syntax and Cabal
  • check the resulting Hackage page
  • post the candidate to #hackage and get feedback
  • create, review and merge an update PR at https://github.com/haskell/cabal-website, possibly touching only download.html
  • release the candidate
  • cd cabal-website; sftp cabal-site@webhost.haskell.org
  • cd cabal
  • put download.html
  • exit
  • verify that the link to release notes inside changelog on Hackage works
  • git tag -s Cabal-vx.x.x.x
  • git push upstream --tags
  • wait (sometimes hours) until CDN kicks in and verify at https://www.haskell.org/cabal/download.html that it looks fine and new links work
  • party

cabal-install

  • bump cabal package deps and versions, probably as part of the sweep above
  • (probably) bump cabal version in doc/conf.py, Cabal/Makefile and .gitlab-ci.yml
  • update cabal-install/changelog and release-notes/cabal-install-x.x.x.x.md using changelog-d and PR log obtained with something like git log Cabal-v3.6.3.0..3.8
  • copy changelog and release notes to master branch
  • cabal check in all relevant directories
  • cabal sdist
  • upload candidate for cabal-install-solver and cabal-install
  • check the resulting Hackage page
  • post the candidate to #hackage and get feedback

TODO

Misc

Related tickets (some possibly outdated; please copy the relevant content and close as appropriate and remove from this list; also, add others): https://github.com/haskell/cabal/issues/3181 https://github.com/haskell/cabal/issues/7298 https://github.com/haskell/cabal/issues/7289

All below this line is outdated, but should be scavenged for creating a new release checklist above this line.

The last content of https://github.com/haskell/cabal/blob/master/release-checklist.md

For major release

  • Add new SPDX License list data

For release for new GHC version:

  • Update GHC flags in normaliseGhcArgs, and add the GHC version to supportedGHCVersions (Distribution.Simple.Program.GHC)
  • Update Language.Haskell.Extension list, if there are new GHC extensions
  • Update setupMinCabalVersionConstraint (in Distribution.Client.ProjectPlanning)
  • Update Cabal.Distribution.Simple.GHC to include new GHC version

The last content of https://github.com/haskell/cabal/wiki/Making-a-release

Pre-work

You will need to to

  • have SFTP access to www-origin.haskell.org (ask admin@haskell.org),
  • be in the cabal group on that server (ask admin@haskell.org), and
  • be listed as a maintainer of the Cabal and cabal-install packages on Hackage (ask one of the existing maintainers).

Also ensure that you have the following setup:

  • A GPG key - for signing the release tags. Check with gpg --list-keys
  • GHC and the profiling libraries installed 
# Check out the major branch you're making a release based on (you might need -b if it doesn't exist).
git checkout X.YY

# Make sure you have all the changes.
git pull

# Repeat for every commit in master that should be part of this release.
git cherry-pick -x <commit on master>

Make a release of Cabal, the library

# The version you're releasing.
export VERSION=X.YY.M.P

# Check what's new since the previous release of Cabal.
git log Cabal-v<previous release>.. -- Cabal/

# Update the changelog by summarizing the above commit log (feel free to
# editorialize).
cd Cabal
$EDITOR changelog

# Bump the version number (depending on if this is a major, minor, or patch release).
$EDITOR Cabal.cabal
$EDITOR Makefile

# Commit the changes.
git commit -am "Bump Cabal version number to v${VERSION}"

# Make sure that the library builds and that the tests pass.
cabal sandbox init
cabal clean
cabal install --enable-tests --only-dependencies
cabal configure --enable-tests
cabal build
cabal test

# Push to the build bot (https://travis-ci.org/haskell/cabal) and wait for
# the results. This exercises additional GHC versions and can take a couple of hours.
git push

# Update the Makefile for the release (KIND=cabal-latest, SSH_USER=<you>).
# These changes shouldn't be committed and can be reverted once the release is done.
$EDITOR Makefile

# Make the release (includes uploading the tarball to haskell.org/cabal).
make release
# TODO(rthomas) The `-latest` symlinks still need to be updated, this is a bit of a pain with sftp.

# Upload the tarball to Hackage as well.
cabal upload dist/Cabal-${VERSION}.tar.gz

# Tag the release - you will need to unlock your GPG key to sign this (you should be prompted)
git tag -a -s -m "Cabal ${VERSION}" Cabal-v${VERSION}
git push && git push --tags

# Update the website. Change the links in download.html to point to the latest release.
# ssh haskell.org
# $EDITOR /home/web/haskell.org/cabal/download.html
# TODO(rthomas) - This needs to be downloaded with sftp, edited and then uploaded again...

Make a release of cabal-install, the executable

Make sure the corresponding Cabal library version (e.g. the one you built above) is installed before you start.

# The version you're releasing.
export VERSION=X.YY.M.P

# Check what's new since the previous release of Cabal.
git log cabal-install-v<previous release>.. -- cabal-install/

# Update the changelog by summarizing the above commit log (feel free to
# editorialize).
cd cabal-install
$EDITOR changelog

# Bump the version number (depending on if this is a major, minor, or patch
# release). You might need to bump the dependency on Cabal as well, if this
# cabal-install release should accompany a new major Cabal release.
$EDITOR cabal-install.cabal
$EDITOR bootstrap.sh

# Commit the changes.
git commit -am "Bump cabal-install version number to v${VERSION}"

# Make sure that the executable builds.
cabal update
cabal sandbox init
#cabal sandbox add-source ../Cabal  # If you're building against in-tree Cabal
cabal clean
cabal install --only-dependencies
cabal configure
cabal build

# Make sure bootstrapping works.
cabal sdist
cp dist/cabal-install-${VERSION}.tar.gz /tmp
pushd /tmp
tar zxf cabal-install-${VERSION}.tar.gz 
cd cabal-install-${VERSION}
sh bootstrap.sh 
popd

# Push to the build bot (https://travis-ci.org/haskell/cabal) and wait for
# the results. This exercises additional GHC versions.
git push

# Upload to Hackage.
cabal upload dist/cabal-install-${VERSION}.tar.gz

# Tag the release.
git tag -a -s -m "cabal-install ${VERSION}" cabal-install-v${VERSION}
git push && git push --tags

# Update the website. Change the links in download.html to point to the latest release.
sftp cabal-site@www-origin.haskell.org
cd cabal/release
mkdir cabal-install-$(VERSION)
cd cabal-install-$(VERSION)
lcd dist
put cabal-install-$(VERSION).tar.gz
# TODO(rthomas) the cabal-install-latest symlink still needs to be updated

# Update the download.html page
# Update the GitHub releases page

Clone this wiki locally