Maintainer guide¶
Pre-release steps¶
- Ensure
release
andstable
branches merged tomaster
- Ensure integration tests pass on a representative Windows, Mac OS X, and Linux (Linux
is handled by Jenkins automatically):
stack install --pedantic && stack test --pedantic --flag stack:integration-tests
. The actual release script will perform a more thorough test for every platform/variant prior to uploading, so this is just a pre-check - Ensure
stack haddock
works (Travis CI now does this) - Stack builds with
stack-7.8.yaml
(Travis CI now does this) - stack can build the wai repo
- Running
stack build
a second time on either stack or wai is a no-op - Build something that depends on
happy
(suggestion:hlint
), sincehappy
has special logic for moving around thedist
directory - In master branch:
- stack.cabal: bump the version number to release (even third component)
- ChangeLog: rename the "unreleased changes" section to the new version
- Cut a release candidate branch
rc/vX.Y.Z
from master - In master branch:
- stack.cabal: bump version number to unstable (odd third component)
- Changelog: add new "unreleased changes" section
- stack.yaml: bump to use latest LTS version, and check whether extra-deps still needed
- In RC branch:
- Update the ChangeLog
(this comparison
is handy):
- Check for any important changes that missed getting an entry in Changelog
- Check for any entries that snuck into the previous version's changes due to merges
- Review documentation for any changes that need to be made
- Search for old Stack version, unstable stack version, and the next "obvious" version in sequence (if doing a non-obvious jump) and replace with new version
- Look for any links to "latest" documentation, replace with version tag
- Ensure all documentation pages listed in
mkdocs.yaml
- Update the ISSUE_TEMPLATE.md to point at the new version.
- Check that any new Linux distribution versions added to
etc/scripts/release.hs
andetc/scripts/vagrant-releases.sh
- Check for new FreeBSD release
- Check that no new entries need to be added to
releases.yaml,
install_and_upgrade.md,
and
README.md
- Remove unsupported/obsolete distribution versions from install_and_upgrade.md, and perhaps from the release process.
- Update the ChangeLog
(this comparison
is handy):
Release process¶
See stack-release-script's README for requirements to perform the release, and more details about the tool.
-
Create a new draft Github release with tag and name
vX.Y.Z
(where X.Y.Z is the stack package's version), targetting the RC branch -
On each machine you'll be releasing from, set environment variables:
GITHUB_AUTHORIZATION_TOKEN
,AWS_ACCESS_KEY_ID
,AWS_SECRET_ACCESS_KEY
,AWS_DEFAULT_REGION
.Note: since one of the tools (rpm-s3 on CentOS) doesn't support AWS temporary credentials, you can't use MFA with the AWS credentials (
AWS_SECURITY_TOKEN
is ignored). -
On a machine with Vagrant installed:
- Run
etc/scripts/vagrant-releases.sh
- Run
-
On Mac OS X:
- Run
etc/scripts/osx-release.sh
- Run
-
On Windows:
- Ensure your working tree is in
C:\stack
(or a similarly short path) - Run
etc\scripts\windows-releases.bat
- Release Windows installers. See stack-installer README
- Ensure your working tree is in
-
Publish Github release
-
Upload package to Hackage:
stack upload . --pvp-bounds=both
-
On a machine with Vagrant installed:
- Run
etc/scripts/vagrant-distros.sh
- Run
-
Edit stack-setup-2.yaml, and add the new linux64 stack bindist
-
Submit a PR for the haskell-stack Homebrew formula
- Be sure to update the SHA sum
- The commit message should just be
haskell-stack <VERSION>
-
Push signed Git tag, matching Github release tag name, e.g.:
git tag -d vX.Y.Z && git tag -u 0x575159689BEFB442 vX.Y.Z && git push origin vX.Y.Z
-
Reset the
release
branch to the released commit, e.g.:git checkout release && git merge --ff-only vX.Y.Z && git push origin release
-
Update the
stable
branch similarly -
Delete the RC branch (locally and on origin)
-
Activate version for new release tag on readthedocs.org, and ensure that stable documentation has updated
-
Upload haddocks to Hackage:
etc/scripts/upload-haddocks.sh
-
Merge any changes made in the RC/release/stable branches to master.
-
Announce to haskell-cafe@haskell.org haskell-stack@googlegroups.com commercialhaskell@googlegroups.com mailing lists
-
Keep an eye on the Hackage matrix builder
Setting up a Windows VM for releases¶
These instructions are a bit rough, but has the steps to get the Windows machine set up.
-
Download VM image: https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/mac/
-
Launch the VM using Virtualbox and the image downloaded
-
Adjust settings:
- Number of CPUs: match the host
- Memory: at least 3 GB
- Video RAM: the minimum recommended by Virtualbox
- Enable 3D and 2D accelerated mode
- Enabled shared clipboard (both directions)
-
Install the VMware guest additions, and reboot
-
Configure a shared folder for your home directory on the host, and mount it on Z:
-
Install Windows SDK (for signtool): http://microsoft.com/en-us/download/confirmation.aspx?id=8279
-
Install msysgit: https://msysgit.github.io/
-
Install nsis-2.46.5-Unicode-setup.exe from http://www.scratchpaper.com/
9: Install Stack using the Windows 64-bit installer
-
Visit https://hackage.haskell.org/ in Edge to ensure system has correct CA certificates
-
Get the object code certificate from password-store, in
certificates/code_signing/fpcomplete_corporation_startssl_2015-09-22.pfx
. Double click it in explorer and import it -
Run in command prompt:
md C:\p md C:\p\tmp cd \p md c:\tmp
-
Create
C:\p\env.bat
:SET STACK_ROOT=C:\p\.sr SET TEMP=C:\p\tmp SET TMP=C:\p\tmp SET PATH=C:\Users\IEUser\AppData\Roaming\local\bin;"c:\Program Files\Git\usr\bin";"C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin";%PATH%
-
Run
C:\p\env.bat
(do this every time you open a new command prompt) -
Import the
dev@fpcomplete.com
(0x575159689BEFB442) GPG secret key -
Run in command prompt (adjust the
user.email
anduser.name
settings):stack setup stack install cabal-install md %HOMEPATH%\.ssh copy z:\.ssh\id_rsa %HOMEPATH%\.ssh git config --global user.email manny@fpcomplete.com git config --global user.name "Emanuel Borsboom" git config --global push.default simple git config --global core.autocrlf true git clone git@github.com:commercialhaskell/stack.git git clone git@github.com:borsboom/stack-installer.git
Adding a new GHC version¶
-
Push new tag to our fork:
git clone git@github.com:commercialhaskell/ghc.git cd ghc git remote add upstream git@github.com:ghc/ghc.git git fetch upstream git push origin ghc-X.Y.Z-release
-
Publish a new Github release with tag
ghc-X.Y.Z-release
and same name. -
Down all the relevant GHC bindists from https://www.haskell.org/ghc/download_ghc_X_Y_Z and upload them to the just-created Github release (see stack-setup-2.yaml for the ones we used in the last GHC release).
In the case of OS X, repackage the
.xz
bindist as a.bz2
, since OS X does not includexz
by default or provide an easy way to install it. -
Build any additional required bindists (see below for instructions)
- libtinfo6 (etc/vagrant/fedora24-x86_64)
-
Edit stack-setup-2.yaml and add the new bindists, pointing to the Github release version. Be sure to update the
content-length
andsha1
values.
Building GHC¶
Set the GHC_VERSION
environment variable to the version to build.
For GHC >= 7.10.2, run (from here):
git config --global url."git://github.com/ghc/packages-".insteadOf git://github.com/ghc/packages/ && \
git clone -b ghc-${GHC_VERSION}-release --recursive git://github.com/ghc/ghc ghc-${GHC_VERSION} && \
cd ghc-${GHC_VERSION}/ && \
cp mk/build.mk.sample mk/build.mk && \
sed -i 's/^#BuildFlavour *= *perf$/BuildFlavour = perf/' mk/build.mk && \
./boot && \
./configure --enable-tarballs-autodownload && \
sed -i 's/^TAR_COMP *= *bzip2$/TAR_COMP = xz/' mk/config.mk && \
make -j$(cat /proc/cpuinfo|grep processor|wc -l) && \
make binary-dist
GHC 7.8.4 is slightly different:
git config --global url."git://github.com/ghc/packages-".insteadOf git://github.com/ghc/packages/ && \
git clone -b ghc-${GHC_VERSION}-release --recursive git://github.com/ghc/ghc ghc-${GHC_VERSION} && \
cd ghc-${GHC_VERSION}/ && \
./sync-all --extra --nofib -r git://git.haskell.org get -b ghc-7.8 && \
cp mk/build.mk.sample mk/build.mk && \
sed -i 's/^#BuildFlavour *= *perf$/BuildFlavour = perf/' mk/build.mk && \
perl boot && \
./configure && \
sed -i 's/^TAR_COMP *= *bzip2$/TAR_COMP = xz/' mk/config.mk && \
make -j$(cat /proc/cpuinfo|grep processor|wc -l) && \
make binary-dist