Releases¶
To do - Simplify the branch or version structure
Just release from the master
branch (but keep the stable
branch
tracking the latest stable release plus updates to documentation).
To do - Remove the -static
version
At some point (a couple of major releases after Stack 2.3.1), remove the
-static
version from
https://github.com/commercialhaskell/stackage-content/blob/master/stack/releases.yaml.
People still using that will get an error, and we'll add a release note to
switch over to https://get.haskellstack.org/stable/linux-x86_64.tar.gz
instead (and note that www.stackage.org/stack is deprecated).
Version scheme¶
- Versions with an even second component are development versions (the
master
branch) - Versions with an odd second component are stable versions (the
stable
branch, or in arc/vX.Y
release candidate branch for not-yet-released versions) - Versions with an even third component (e.g. 1.6.2 and 1.7.0) are unreleased versions
- Versions with an odd third component (e.g. 1.6.1 or 1.7.3) are released versions
- Pre-release unstable binaries will be released with the date as the fourth component (e.g. 1.6.0.20171129)
- Release candidate binaries will be released with an even third component and and odd number as the fourth component (e.g. 1.7.0.1)
- Hackage-only dependency compatibility patch releases add a fourth patchlevel
component (e.g. v1.7.3.1, in the
release
branch) - All branches except
release
(which matches exactly the most recent release) must have an even third component (development) - Branches other than
stable
,release
, and arc/vX.Y
release candidate will always have a0
third component (e.g. 1.7.0).
Examples:
1.7.0.0
: v1.7.x series pre-release branch (v1.7
branch)1.7.0.1
: release candidate for first release of v1.7.x series (v1.7
branch)1.7.0.2
: continuing development on pre-release branch1.7.0.3
: second release candidate for first release of v1.7.x series (v1.7
branch)1.7.1
: first release of the 1.7.x series (release
branch)1.7.2.0
: development for second release of 1.7.x series (stable
branch)1.7.2.1
: release candidate for second release of 1.7.x series (stable
branch)1.7.3
: second release of 1.7.x series (release
branch)1.7.3.1
: first hackage-only patch of 1.7.3 (release
branch)1.7.3.2
: second hackage-only patch of 1.7.3 (release
branch)1.8.0
: unstable development code (master
branch)1.8.0.20181004
: pre-release snapshot of unstable version (master
branch)
Pre-release checks¶
- Check for any P0 and P1 issues that should be dealt with before release
- Check for un-merged pull requests that should be merged before release
- Ensure the
release
andstable
branches are merged to themaster
branch - Check copyright dates, and update if needed
- Ensure CI matrices in docs (travis-complex, appveyor, azure) have current stackage snapshots and GHC versions (e.g. https://github.com/commercialhaskell/stack/pull/4565/files)
-
Update the
stack-*.yaml
that uses anightly
snapshot to the latest nightly (go over the extra-deps too) and ensure the project builds and tests pass. For example, command: -
Ensure integration tests pass on a Windows, macOS, and Linux. Do so by checking that the latest nightly build for the
master
branch succeeded in Azure DevOps (or kick one off manually if any significant changes were made since the last automated build).
Release preparation¶
A: In the master
branch¶
-
package.yaml
: bump to the next release candidate version (bump the second component to the next odd number, ensure the third component is0
, and add patchlevel0
; e.g. from1.8.0
to1.9.0.0
).Attention
Be sure to update also
stack.cabal
(for example by usingstack build --dry-run
). -
ChangeLog.md
: Check for any entries that snuck into the previous version's changes due to merges (git diff origin/stable HEAD ChangeLog.md
)
B: Create a new release candidate branch¶
Cut a new release candidate (RC) branch named rc/vX.Y
from the master
branch.
C: Return to the master
branch¶
-
package.yaml
: bump version to the next unstable version (bump the second component to the next even number, ensure the third component is0
; e.g. from1.9.0
to1.10.0
).Attention
Be sure to update also
stack.cabal
(for example by usingstack build --dry-run
). -
Changelog.md
:- Change the title of the existing Unreleased changes section to what
will be the next final (non-RC) release (e.g.
v2.1.1
). -
Add new "Unreleased changes" section:
- Change the title of the existing Unreleased changes section to what
will be the next final (non-RC) release (e.g.
D: In the release candidate branch¶
Review documentation for any changes that need to be made:
- Ensure all the documentation pages are listed in the
mkdocs.yaml
file. Usegit diff --stat origin/stable..HEAD doc/
to look for new or deleted files. - Any new documentation pages should have the "may not be correct for the released version of Stack" warning at the top.
-
Search for old Stack version, unstable Stack version, and the next "obvious" possible versions in sequence, and
UNRELEASED
and replace with next release version (X.Y.1
, where Y is odd).Attention
Do NOT update the Dockerfiles in stackage/automated/dockerfiles yet. That step will come later.
Attention
Do NOT update the repository's issue and pull request templates (in the
.github
directory)to point at the new release version yet! -
Search for old resolvers, set to latest resolver (e.g. in
doc/GUIDE.md
where it references the "currently the latest LTS") - Look for any links to "latest" (
latest/
) documentation, replace with version tag
Check for any platform entries that need to be added to (or removed from):
- releases.yaml,
- install_and_upgrade.md,
- get-stack.sh,
- doc/README.md, and
get.haskellstack.org
redirects.
E: For the first release candidate¶
- Re-do the pre-release checks (see the section above).
-
package.yaml
: bump to first odd patchlevel version (e.g.X.Y.0.1
).Attention
Be sure to update also
stack.cabal
(for example by usingstack build --dry-run
). -
ChangeLog.md
: Rename the “Unreleased changes” section to the same version aspackage.yaml
, and mark it clearly as a release candidate (e.g.vX.Y.0.1 (release candidate)
). Remove any empty sections. - Follow the steps in the Release process section below that apply to a release candidate.
F: For any subsequent release candidates¶
- Re-do the pre-release checks (see the section above).
-
package.yaml
: bump to next odd patchlevel version (e.g.X.Y.0.3
).Attention
Be sure to update also
stack.cabal
(for example by usingstack build --dry-run
). -
ChangeLog.md
: Rename the "Unreleased changes" section to the new version, clearly marked as a release candidate (e.g.vX.Y.0.3 (release candidate)
). Remove any empty sections. - Follow the steps in the Release process section below that apply to a release candidate.
G: For the final release¶
- Re-do the pre-release checks (see the section above).
-
package.yaml
: bump version to odd last component and no patchlevel (e.g. fromX.Y.0.2
toX.Y.1
).Attention
Be sure to update also
stack.cabal
(for example by usingstack build --dry-run
). -
ChangeLog.md
: consolidate all the release candidate changes into a single section for the final release version. - Follow all of the steps in the Release process section below that apply to a final release.
Release process¶
The release process differs between a first, second etc release candidate and a final release.
A: Integration tests workflow passes¶
Ensure that the GitHub Integration Tests workflow passes on the branch that you are releasing.
This workflow will run automatically for the rc/*
branch.
B: Push a Git tag¶
Push a Git tag. The tag should be rc/vX.Y.Z.A
, with X.Y.Z.A
matching the
version in package.yaml
.
For example, command:
C: Edit the draft GitHub release, and publish it¶
Wait for the GitHub Integration Tests workflow to complete for the branch you just created. This will create a draft GitHub release and upload the bindists (plus signatures and hashes) to it.
Edit the draft GitHub release:
- Add
(release candidate)
to the name field and ensure that This is a pre-release is checked. - Add the ChangeLog to the description.
Publish the GitHub release.
D: Update versions and ChangeLog.md
for 'unreleased'¶
In the rc/vX.Y
branch:
-
package.yaml
: bump the version number. Bump the fourth component to an even number (e.g. from 1.7.0.1 to 1.7.0.2).Attention
Be sure to update also
stack.cabal
(for example by usingstack build --dry-run
). -
ChangeLog.md
: Add an “Unreleased changes” section (update the “changes since” version):
E: Announce the release candidate¶
Announce the release candidate to the following mailing lists
-
haskell-cafe@haskell.org
Note
You have to be a member of the mailing list to post to it. See the list's interface
-
haskell-stack@googlegroups.com
Note
Members of the group can post but posts from new members are held for moderation.
-
commercialhaskell@googlegroups.com
Note
Members of the group can post but posts from new members are held for moderation.
Announce the release candidate on the Haskell Community.
Announce the release candidate in the #stack-users
channel of the Haskell
Foundation's Slack workspace.
Announce the release candidate in Reddit's Haskell community.
In each case, use the subject (change 'first' to 'second' etc for subsequent release candidates):
ANN: first release candidate for stack-X.Y.Z
In the message, include:
- a link to the release on GitHub
(
https://github.com/commercialhaskell/stack/releases/tag/rc/vX.Y.Z.A
) to download it - the release description from Github.
A: Integration tests workflow passes¶
Ensure that the GitHub Integration Tests workflow passes on the branch that you are releasing.
This workflow will run automatically for rc/*
branches.
B: Push a Git tag¶
Push a Git tag. The tag should be vX.Y.Z
, where X.Y.Z
matches the
version in package.yaml
.
For example, command:
C: Edit the draft GitHub release, and publish it¶
Wait for the GitHub Integration Tests workflow to complete for the tag you just created. This will create a draft GitHub release and upload the bindists (plus signatures and hashes) to it.
Edit the draft GitHub release:
- Add the ChangeLog to the description.
-
Get the list of contributors to the release and add it to the description. For example, command:
Publish the GitHub release.
D: Upload to Hackage and reset branches¶
Upload the stack
package to Hackage with the command:
Reset the release
branch to the released commit. For example, with the
commands:
Update the stable
branch to the released commit. For example, with the
commands:
Merge any changes made in the RC, release
or stable
branches to the
master
branch. Be careful about version and ChangeLog.md
. It is best to
do this by making a ci/merge-stable-to-master
branch and waiting for CI to
pass, then merging. If anything is complicated to merge, consider making it
a pull request and getting it reviewed rather than merging immediately.
Delete the RC branch, both locally and on the remote. For example with the commands:
E: Activate the version on Read The Docs¶
Activate the version for new release tag, on readthedocs.org.
Ensure that the stable
documentation has updated.
F: Update get.haskellstack.org¶
Update get.haskellstack.org /stable and /upgrade rewrite rules with the new version.
Sync the application in ArgoCD.
Test with the command:
and make sure it redirects to the new version.
G: Update versions and ChangeLog.md
for 'unreleased'¶
In the stable
branch:
-
package.yaml
: bump the version number. Bump the third component to an even number (e.g. from1.6.1
to1.6.2
).Attention
Be sure to update also
stack.cabal
(for example by usingstack build --dry-run
). -
ChangeLog.md
: Add an “Unreleased changes” section (update the “changes since” version):
H: Update the repository's issue and pull request templates¶
The repository's issue and pull request templates are the .github
directory. Update them to refer to the new release version (X.Y.Z
).
I: Announce the release¶
Announce the release to the following mailing lists
-
haskell-cafe@haskell.org
Note
You have to be a member of the mailing list to post to it. See the list's interface
-
haskell-stack@googlegroups.com
Note
Members of the group can post but posts from new members are held for moderation.
-
commercialhaskell@googlegroups.com
Note
Members of the group can post but posts from new members are held for moderation.
Announce the release on the Haskell Community.
Announce the release in the #stack-users
channel of the Haskell
Foundation's Slack workspace.
Announce the release in Reddit's Haskell community.
In each case, use the subject:
* ANN: stack-X.Y.Z
In the message, include:
- the release description from Github.
J: Update Docker images¶
Docker Hub includes Docker images under `fpco/stack-build'.
Update those images with a new version:
-
Under commercialhaskell/stackage/automated/dockerfiles, add
lts-X.Y/Dockerfile
(whereX.Y
is the latest Stackage Haskell LTS version), containing (whereX.Z
is the previous Haskell LTS version, andX.Y.Z
is the newly released Stack version): -
Run
./build.sh lts-X.Y
. Then test that the new image has the new version of Stack. For example, command: -
Use the following commands to push the new image to the registry: