Merge pull request #5397 from commercialhaskell/stable-into-master

Stable into master

Author: snoyberg

doc/README.md

@@ -17,6 +17,9 @@ It features:
 
 #### How to install
 
+Stack can be installed on most Unix-like (Un*x) operating systems, including
+macOS, and on Windows.
+
 For most Un*x operating systems, the easiest way to install is to run:
 
     curl -sSL https://get.haskellstack.org/ | sh

doc/install_and_upgrade.md

@@ -250,7 +250,7 @@ or:
 
 * Ensure you have required system dependencies installed.  These include GCC, GNU make, xz, perl, libgmp, libffi, and zlib.  We also recommend Git and GPG.  To install these using your package manager:
     * Debian / Ubuntu: `sudo apt-get install g++ gcc libc6-dev libffi-dev libgmp-dev make xz-utils zlib1g-dev git gnupg netbase`
-    * Fedora / CentOS: `sudo dnf install perl make automake gcc gmp-devel libffi zlib xz tar git gnupg` (use `yum` instead of `dnf` on CentOS and Fedora <= 21)
+    * Fedora / CentOS: `sudo dnf install perl make automake gcc gmp-devel libffi zlib zlib-devel xz tar git gnupg` (use `yum` instead of `dnf` on CentOS and Fedora <= 21)
         * Fedora 24: In order to use `stack setup` on a 32-bit system, you may
           need to run `sudo dnf install ncurses-compat-libs`. If this package is
           not installed, Stack may not be able to install 32-bit GHC versions.

doc/maintainers/ghc.md

@@ -40,7 +40,7 @@
 
         cd stack && ./update-global-hints.hs ghc-X.Y.Z
 
-    and commit the changes.
+    and commit and push the changes.
 
 
 ## Building GHC

doc/maintainers/releases.md

@@ -84,13 +84,13 @@ Examples:
         * 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). 
-          * Do **NOT** update the Dockerfiles in [stackage/automated/dockerfiles](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/) yet; that will come later)
-            * Do __NOT__ update templates in `.github` to point at the new release version yet!
+            * Do **NOT** update the Dockerfiles in [stackage/automated/dockerfiles](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/) yet; that will come later)
+            * Do **NOT** update templates in `.github` 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 that for any platform entries that need to be added to (or removed from)
       [releases.yaml](https://github.com/fpco/stackage-content/blob/master/stack/releases.yaml),
-      [install_and_upgrade.md](https://github.com/commercialhaskell/stack/blob/master/doc/install_and_upgrade.md), [get-stack.sh](https://github.com/commercialhaskell/stack/blob/master/etc/scripts/get-stack.sh), and [doc/README.md](https://github.com/commercialhaskell/stack/blob/master/doc/README.md).
+      [install_and_upgrade.md](https://github.com/commercialhaskell/stack/blob/master/doc/install_and_upgrade.md), [get-stack.sh](https://github.com/commercialhaskell/stack/blob/master/etc/scripts/get-stack.sh), and [doc/README.md](https://github.com/commercialhaskell/stack/blob/master/doc/README.md), and get.haskellstack.org redirects.
     * `package.yaml`: bump to next release candidate version (bump patchlevel (fourth) component to next odd number; e.g. from `1.9.0.0` to `1.9.0.1`)
     * `ChangeLog.md`
         - Rename the “Unreleased changes” section to the same version as package.yaml, and mark it clearly as a release candidate (e.g. `v1.9.0.1 (release candidate)`).  Remove any empty sections.
@@ -114,13 +114,17 @@ Examples:
 
 ## Release process
 
-* Manually trigger the nightly pipeline on Azure Devops for the branch you are releasing, which will build Linux, macOS, and Windows bindists. `[RC]`
+* Trigger the **Integration Tests** workflow on Github Actions for the branch you are releasing, which will build Linux, macOS, and Windows bindists. `[RC]`
 
 * Create a
   [new draft Github release](https://github.com/commercialhaskell/stack/releases/new)
   with tag and title `vX.Y.Z` (where X.Y.Z matches the version in `package.yaml` from the previous step), targeting the RC branch.  In the case of a release candidate, add `(RELEASE CANDIDATE)` to the name field and check the *This is a pre-release* checkbox.  `[RC]`
+    * See previous releases for example formatting and extra info (such as link to website for install instructions).
+    * For release candidates, you should **skip** the list of contributors and the link to the installation instructions.
+    * Include the Changelog in the description.
+    * Use e.g. `git shortlog -s origin/release..HEAD|sed $'s/^[0-9 \t]*/* /'|grep -v azure-pipelines|LC_ALL=C sort -f` to get the list of contributors.
 
-* On each machine you'll be releasing from, set environment variables `GITHUB_AUTHORIZATION_TOKEN` and `STACK_RELEASE_GPG_KEY` (see [stack-release-script's README](https://github.com/commercialhaskell/stack/blob/master/etc/scripts/README.md#prerequisites)). `[RC]`
+* On the machine you'll be releasing from, set environment variables `GITHUB_AUTHORIZATION_TOKEN` and `STACK_RELEASE_GPG_KEY` (see [stack-release-script's README](https://github.com/commercialhaskell/stack/blob/master/etc/scripts/README.md#prerequisites)). `[RC]`
 
 * Upload the Azure bindists built by Azure Pipelines to the Gitlab release `[RC]`
   * Download the bindist artifacts from the Azure DevOps nightly pipeline build, and put the contents under `_release/`.
@@ -130,21 +134,43 @@ Examples:
             stack "etc/scripts/release.hs" --upload-only "$x.upload" "$x.sha256.upload" "$x.asc.upload"
         done
 
+  TODO: have Github Actions do this automatically.
+
 * For any GPG key used to sign an uploaded bindist, ensure that `[email protected]` signs their key and uploads to SKS keyserver pool:
 
   ```
   gpg --sign-key -u 0x575159689BEFB442 <OTHER-KEY-ID>
   gpg --send-keys <OTHER-KEY-ID>
   ```
 
-* Publish Github release. Include the Changelog and in the description and use e.g. `git shortlog -s origin/release..HEAD|sed $'s/^[0-9 \t]*/* /'|grep -v azure-pipelines|LC_ALL=C sort -f` to get the list of contributors. See previous releases for example formatting and extra info (such as link to website for install instructions).  `[RC]`
-
-    * For release candidates, you should skip the list of contributors and the link to the installation instructions.
+* Publish the Github release. `[RC]`
 
 * Push signed Git tag, matching Github release tag name, e.g.: `git tag -d vX.Y.Z; git tag -s -m vX.Y.Z vX.Y.Z && git push -f origin vX.Y.Z`.  `[RC]`
 
 * Upload `stack` package to Hackage: `stack upload . --pvp-bounds=lower`.
 
+    * If you get the error
+
+      > The field "build-tools" is deprecated in the Cabal specification version 2.0. Please use 'build-tool-depends' field
+
+      then edit `stack.cabal` locally and change all instances of
+
+      ```
+      build-tools:
+        hsc2hs
+      ```
+
+      to
+
+      ```
+      build-tool-depends:
+        hsc2hs:hsc2hs
+      ```
+
+      and try again, then discard the local changes to `stack.cabal`.
+
+      Hopefully this issue will be resolved and we can remove this instruction (alternatively, we could use a `verbatim` field in `package.yaml`).
+
 * 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
@@ -153,7 +179,7 @@ Examples:
   [readthedocs.org](https://readthedocs.org/projects/stack/versions/), and
   ensure that stable documentation has updated.
 
-* Update [get.haskellstack.org /stable rewrite rules](https://gitlab.com/fpco/operations/devops/-/blob/master/kubernetes/fpco-prod-v3/specs/20_get-haskellstack_ingress.yaml) and apply the manifest.
+* Update [get.haskellstack.org /stable and /upgrade rewrite rules](https://gitlab.com/fpco/operations/kube/fpcomplete-sites-project/-/blob/master/fpcomplete-redirects/get-haskellstack_virtualservice.yaml) with the new version and [sync the application in ArgoCD](https://v4.fpcomplete.com/argo-cd/applications/fpcomplete-redirects).
 
     * Test with `curl -vL https://get.haskellstack.org/stable/linux-x86_64.tar.gz >/dev/null`, make sure it redirects to the new version
 
@@ -186,13 +212,13 @@ Examples:
 * Merge any changes made in the RC/release/stable branches to master (be careful about version and changelog).   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 PR and getting it reviewed rather than merging immediately.
 
 * Announce to [email protected], [email protected],
-  [email protected] mailing lists, subject `ANN: stack-X.Y.Z` (or `ANN: stack-X.Y release candidate`), containing the markdown for the release description from Github. `[RC]`
+  [email protected] mailing lists, subject `ANN: stack-X.Y.Z` (or `ANN: stack-X.Y release candidate`), containing the release description from Github. `[RC]`
 
     * For release candidates, also include a link to the Github Release (`https://github.com/commercialhaskell/stack/releases/tag/vX.Y.Z`) to download it. `[RC]`
 
 * Update fpco/stack-build Docker images with new version
 
-  * Under [commercilhaskell/stackage/automated/dockerfiles](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/), add `lts-X.Y/Dockerfile` (where `X.Y` is the latest stackage LTS version), containing (note where X.Z is the previous LTS version, and X.Y.Z is the newly released stack version)
+  * Under [commercialhaskell/stackage/automated/dockerfiles](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/), add `lts-X.Y/Dockerfile` (where `X.Y` is the latest stackage LTS version), containing (note where X.Z is the previous LTS version, and X.Y.Z is the newly released stack version)
 
     ```
     FROM $DOCKER_REPO:lts-X.Z
@@ -204,9 +230,10 @@ Examples:
 
   * Run `./build.sh --push lts-X.Y && ./build.sh --push --small lts-X.Y` to push the new image to the registry.
 
+
 ## Build Linux static binary distribution with Nix
 
-NOTE: We have switched back to Alpine Linux for building static binaries, done by CI.
+**NOTE: We have switched back to Alpine Linux for building static binaries, done by CI.  Leaving this section for future reference.**
 
 These instructions are tested on Ubuntu 16.04, but theoretically should work on any Linux distribution.