Maintainer guide

Pre-release steps

  • Ensure release and stable branches merged to master
  • 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), since happy has special logic for moving around the dist 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 and etc/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.

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
  • On Mac OS X:

    • Run etc/scripts/osx-release.sh
  • 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
  • Publish Github release

  • Upload package to Hackage: stack upload . --pvp-bounds=both

  • On a machine with Vagrant installed:

    • Run etc/scripts/vagrant-distros.sh
  • 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>
  • Flag the Arch Linux package as out-of-date

  • 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.

  1. Download VM image: https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/mac/

  2. Launch the VM using Virtualbox and the image downloaded

  3. 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)
  4. Install the VMware guest additions, and reboot

  5. Configure a shared folder for your home directory on the host, and mount it on Z:

  6. Install Windows SDK (for signtool): http://microsoft.com/en-us/download/confirmation.aspx?id=8279

  7. Install msysgit: https://msysgit.github.io/

  8. Install nsis-2.46.5-Unicode-setup.exe from http://www.scratchpaper.com/

9: Install Stack using the Windows 64-bit installer

  1. Visit https://hackage.haskell.org/ in Edge to ensure system has correct CA certificates

  2. 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

  3. Run in command prompt:

    md C:\p
    md C:\p\tmp
    cd \p
    md c:\tmp
    
  4. 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%
    
  5. Run C:\p\env.bat (do this every time you open a new command prompt)

  6. Import the dev@fpcomplete.com (0x575159689BEFB442) GPG secret key

  7. Run in command prompt (adjust the user.email and user.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 include xz 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 and sha1 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