Merge branch 'stable'

CONTRIBUTING.md

@@ -304,38 +304,100 @@ Where again, `<PATTERN>` is the name of the folder listed in the
 [test/integration/tests/](https://github.com/commercialhaskell/stack/tree/master/test/integration/tests)
 folder.
 
-## CI Build rules
+## Continuous integration (CI)
 
-We use [Azure](https://dev.azure.com/commercialhaskell/stack/_build)
-to do CI builds on Stack. There are two types of build which happens
-there:
+We use [GitHub Actions](https://docs.github.com/en/actions) to do CI on Stack.
+The configuration of the workflows is in the YAML files in `.github/workflows`.
+The current active workflows are:
 
-### Test suite build
+### Linting - `lint.yml`
 
-This builds the code with `--pedantic`, performs hlint checks and it
-runs all test suites on multiple GHC/OS configuration. These are the
-rules for triggering it:
+This workflow will run if:
+* there is a pull request
+* commits are pushed to these branches: `master`, `stable` and `rc/**`
 
-* CI will run this if commits are pushed to stable, master branch
-* CI will run this for any branches starting with `ci/`
-* CI will run this for all new PR's.
+The workflow has one job (`style`). It runs on `ubuntu` only and applies
+yamllint and Hlint.
 
-### Integration based build
+### Test suite - `unit-tests.yml`
 
-This build runs the integration tests in the Stack codebase. This is
-scheduled to run daily once for both the stable and master branches.
+This workflow will run if:
+* there is a pull request
+* commits are pushed to these branches: `master`, `stable` and `rc/**`.
+* requested
 
-Also, you can manually run this on a specific branch from the Azure UI
-if you have the appropriate permissions. If you'd specifically like a
-branch or PR to run integration tests, add a comment in the PR and we
-can queue one up.
+The workflow has two jobs: `pendantic` and `unit-tests`.
 
-### Skipping build
+The `pendantic` job runs on `ubuntu` only and builds Stack with the
+`--pedantic` flag.
 
-There are times (like a minor type fix) where you don't want the CI to
-run. For those cases, you can add `[skip ci]` or `[ci skip]` in your
-commit message to skip the builds. For more details,
-[refer here](https://github.com/Microsoft/azure-pipelines-agent/issues/858#issuecomment-475768046).
+The `unit-tests` job runs on a matrix of operating systems and Stack
+project-level YAML configuration files (`stack.yaml`). It builds and tests Stack
+with the following flags: `--haddock --no-haddock-deps`.
+
+Its approach to creating a cache depends on the operating system. Its 'Cache
+dependencies on Unix-like OS' step caches the Stack root on Unix-like operating
+systems. Its 'Cache dependencies on Windows' step caches the same information
+on Windows, but takes into account that a relevant directory is located outside
+of the Stack root.
+
+### Integration-based - `intergration-tests.yml`
+
+This workflow will run if:
+* there is a pull request
+* commits are pushed to these branches: `master`, `stable` and `rc/**`
+* any tag is created
+* requested
+
+The workflow has two jobs: `integration-tests` and `github-release`.
+
+The `integration-tests` job runs on a matrix of operating systems (`ubuntu`,
+`windows` and `macos`) and makes use of the `release.hs` script at
+`etc/scripts`. Its approach to creating a cache is the same as for
+`unit-tests.yml`, described above.
+
+Its 'Install deps and run checks' step uses `release.hs check`.
+
+Its 'Build bindist' step uses `release.hs build`.
+
+Its 'Upload bindist' step uploads artifacts using the name of the runner's
+operating system (`Linux`, `Windows` or `macOS`) as the name for the artifacts.
+
+The `github-release` job needs `integration-tests` and only takes effect if the
+trigger for the workflow was the creation of a tag.
+
+Its steps `Download Linux/Windows/macOS artifact` download the named artifacts
+to path `_release`.
+
+Its step 'Hash and sign assets' makes use of a 'secret' environment variable
+`RELEASE_SIGNING_KEY` established by the owner of the Stack repository. The
+variable contains the private key for the GPG key with ID 0x575159689BEFB442.
+That key is imported into GPG and then used by GPG to create a detached signture
+for each file.
+
+### ARM64 (AArch64) release - `arm64-release.yml`
+
+This workflow will run if:
+* there is a pull request
+* commits are pushed to these branches: `master`, `stable` and `rc/**`
+* any tag is created
+* requested
+
+The workflow has one job (`arm64`). It runs on a self-hosted runner for Linux
+and ARM64. It makes use of Docker and a Docker file at
+`etc/dockerfiles/arm64.Dockerfile`.
+
+Its 'Build bindist' step makes use of a compiled version of `release.hs` script
+at `etc/scripts` to command `release build`.
+
+Its 'Upload bindist' step uploads artifacts using `Linux-ARM64` as the name for
+the artifacts.
+
+### Inactive - `stan.yml`
+
+Stan is a Haskell static analysis tool. As of 29 August 2022, it does not
+support GHC >= 9.0.1 and Stack is built with GHC >= 9.2.4. Consequently, this
+workflow does not run. Its intent is to apply Stan to Stack.
 
 ## Slack channel
 

doc/GUIDE_advanced.md

@@ -386,10 +386,19 @@ documentation.
 
 ## Continuous integration (CI)
 
-### Travis with caching
+### GitHub Actions
 
-This content has been moved to a dedicated
-[Travis CI document](https://docs.haskellstack.org/en/stable/travis_ci/).
+The Stack repository uses GitHub Actions for its own CI. For further
+information, see the guide to
+[contributing](CONTRIBUTING.md#continuous-integration-ci).
+
+### Azure
+
+For further information, see the [Azure CI](azure_ci.md) documentation.
+
+### Travis
+
+For futher information, see the [Travis CI](travis_ci.md) documentation.
 
 ## Editor integration
 

doc/SIGNING_KEY.md

@@ -2,11 +2,44 @@
 
 # Signing key
 
-Each release of Stack is signed with the GPG key of the person who makes the
-release.
+Each released Stack executable is signed with either:
 
-Authorized keys are themselves signed by the GPG key with ID 0x575159689BEFB442.
-That key, and keys it has signed, have been uploaded to the
+* the GPG key with ID 0x575159689BEFB442; or
+* the GPG key of a person that has been authorised by the GPG key with ID
+  0x575159689BEFB442.
+
+The signature is in an `*.asc` file. For example:
+
+~~~
+stack-2.7.5-linux-x86_64-bin
+stack-2.7.5-linux-x86_64-bin.asc
+~~~
+
+The signature can be verified with GPG, as follows:
+
+~~~
+$ # Receive the public key from a keyserver
+$ gpg --keyserver keyserver.ubuntu.com --recv-keys 0x575159689BEFB442
+$ # Get information about the key
+$ gpg --keyid-format long --list-keys 0x575159689BEFB442
+pub   rsa2048/575159689BEFB442 2015-06-02 [SC]
+      C5705533DA4F78D8664B5DC0575159689BEFB442
+uid                 [ unknown] FPComplete <dev@fpcomplete.com>
+sub   rsa2048/85A738994664AB89 2015-06-02 [E]
+
+$ # Attempt to verify the file using the signature file. The public key has not
+$ # yet been certified with a trusted signature.
+$ gpg --verify stack-2.7.5-linux-x86_64-bin.asc stack-2.7.5-linux-x86_64-bin
+gpg: Signature made 06/03/2022 15:15:21 GMT Standard Time
+gpg:                using RSA key C5705533DA4F78D8664B5DC0575159689BEFB442
+gpg: Good signature from "FPComplete <dev@fpcomplete.com>" [unknown]
+gpg: WARNING: This key is not certified with a trusted signature!
+gpg:          There is no indication that the signature belongs to the owner.
+Primary key fingerprint: C570 5533 DA4F 78D8 664B  5DC0 5751 5968 9BEF B442
+~~~
+
+The GPG key with ID 0x575159689BEFB442, and keys it has signed, have been
+uploaded to the
 [Ubuntu Keyserver](https://keyserver.ubuntu.com/pks/lookup?search=0x575159689BEFB442&fingerprint=on&op=index).
 
 This is the public key block for GPG key ID 0x575159689BEFB442: