diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 58a4d053c7..47582b6a42 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -304,38 +304,100 @@ Where again, `` 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 diff --git a/doc/GUIDE_advanced.md b/doc/GUIDE_advanced.md index 557a407ebe..ee030f98b7 100644 --- a/doc/GUIDE_advanced.md +++ b/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 diff --git a/doc/SIGNING_KEY.md b/doc/SIGNING_KEY.md index f792dfde3d..8fa9a606d0 100644 --- a/doc/SIGNING_KEY.md +++ b/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 +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 " [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: