Merge branch 'master' into fix1369

Author: mpilgrem

CONTRIBUTING.md

@@ -1,5 +1,106 @@
 # Contributors Guide
 
+Thank you for considering contributing to the maintenance or development of
+Stack, or otherwise supporting users of Stack! We hope that the following
+information will encourage and assist you. We start with some advice about
+Stack's goals and governance, and approach to supporting users.
+
+## Stack's goals
+
+Stack's current goals are:
+
+* To provide easy to use tooling for Haskell development
+* To provide complete support for at least the following three development
+  environments: Linux, macOS, and Windows
+* To address the needs of industrial users, open source maintainers, and other
+  people
+* To focus on the 'curated package set' use case
+* To prioritize reproducible build plans
+
+The goals above are not set in stone. However, any major changes to them
+should involve significant public discussion and a public vote by the Stack
+maintainer team.
+
+## Stack's governance
+
+People involved in maintaining or developing Stack with rights to make commits
+to the repository can be classified into two groups: 'committers' and
+'maintainers'.
+
+### Stack's committers
+
+We encourages a wide range of people to be granted rights to make commits to the
+repository.
+
+People are encouraged to take initiative to make non-controversial
+changes, such as documentation improvements, bug fixes, performance
+improvements, and feature enhancements.
+
+Maintainers should be included in discussions of controversial changes and
+tricky code changes.
+
+Our general approach is **"it's easier to ask forgiveness than permission"**. If
+there is ever a bad change, it can always be rolled back.
+
+### Stack's maintainers
+
+Stack's maintainers are long-term contributors to the project. Michael Snoyman
+(@snoyberg) was the founder of Stack, and its initial maintainer - and he has
+added others. Michael's current interests and priorties mean that he is no
+longer actively involved in adding new features to Stack.
+
+Maintainers are recognized for their contributions including:
+
+* Direct code contribution
+* Review of pull requests
+* Interactions on the GitHub issue tracker
+* Documentation management
+* External support - for example, hosting or training
+
+The maintainer team make certain decisions when that is necessary, specifically:
+
+* How to proceed, if there is disagreement on how to do so on a specific topic
+* Whether to add or remove (see further below) a maintainer
+
+Generally, maintainers are only removed due to non-participation or actions
+unhealthy to the project. Removal due to non-participation is not a punishment,
+simply a recognition that maintainership is for active participants only.
+
+We hope that removal due to unhealthy actions will never be necessary, but would
+include protection for cases of:
+
+* Disruptive behavior in public channels related to Stack
+* Impairing the codebase through bad commits/merges
+
+Like committers, maintainers are broadly encouraged to make autonomous
+decisions. Each maintainer is empowered to make a unilateral decision. However,
+maintainers should favor getting consensus first if:
+
+* They are uncertain what is the best course of action
+* They anticipate that other maintainers or users of Stack will disagree on the
+  decision
+
+## Stack's support
+
+A large part of the general discussion around Stack is on support-related
+topics, and that is reflected in the current issue tracker content. Assistance
+in responding to such matters is greatly appreciated.
+
+While support-related matters can be posted here as an 'issue', we encourage the
+use of other forums, in particular
+[Haskell's Discourse](https://discourse.haskell.org/). We also recommend
+Haskell's Discourse for general discussions about Stack's current or desired
+features. Stack is also discussed on Reddit's
+[Haskell community](https://www.reddit.com/r/haskell/).
+
+We encourage use of those other forums because support-related discussions can
+clog up the issue tracker and make it more difficult to maintain the project.
+People needing support may also get a faster and fuller response on other
+forums.
+
+Additions to the issue tracker are better suited to concrete feature proposals,
+bug reports, and other code base discussions (for example, refactorings).
+
 ## Bug Reports
 
 Please [open an issue](https://github.com/commercialhaskell/stack/issues/new)
@@ -19,7 +120,8 @@ If you would like to help with documentation, please note that for most cases
 the Wiki has been deprecated in favor of markdown files placed in a new `/doc`
 subdirectory of the repository itself. Please submit a
 [pull request](https://help.github.com/articles/using-pull-requests/) with your
-changes/additions based off the [the stable branch](https://github.com/commercialhaskell/stack/tree/stable).
+changes/additions based off the
+[the stable branch](https://github.com/commercialhaskell/stack/tree/stable).
 
 The documentation is rendered on [haskellstack.org](http://haskellstack.org) by
 readthedocs.org using Sphinx and CommonMark. Since links and formatting vary
@@ -72,16 +174,18 @@ quality tool.
 
 Note that stack contributors need not dogmatically follow the suggested hints
 but are encouraged to debate their usefulness. If you find a hint is not useful
-and detracts from readability, consider marking it in the [configuration
-file](https://github.com/commercialhaskell/stack/blob/master/.hlint.yaml) to
-be ignored. Please refer to the [HLint manual](https://github.com/ndmitchell/hlint#readme)
+and detracts from readability, consider marking it in the
+[configuration file](https://github.com/commercialhaskell/stack/blob/master/.hlint.yaml)
+to be ignored. Please refer to the
+[HLint manual](https://github.com/ndmitchell/hlint#readme)
 for configuration syntax.
 
-Quoting [@mgsloan](https://github.com/commercialhaskell/stack/pulls?utf8=%E2%9C%93&q=is%3Apr%20author%3Amgsloan):
+Quoting
+[@mgsloan](https://github.com/commercialhaskell/stack/pulls?utf8=%E2%9C%93&q=is%3Apr%20author%3Amgsloan):
 
 > We are optimizing for code clarity, not code concision or what HLint thinks.
 
-You can install HLint with stack. You might want to install it in the global
+You can install HLint with Stack. You might want to install it in the global
 project in case you run into dependency conflicts. HLint can report hints in
 your favourite text editor. Refer to the HLint repository for more details.
 
@@ -100,10 +204,12 @@ $ ./etc/scripts/hlint.sh
 ## Testing
 
 The Stack code has both unit tests and integration tests. Integration tests can
-be found in the [test/integration](https://github.com/commercialhaskell/stack/tree/master/test/integration)
-folder and unit tests, in the [src/test](https://github.com/commercialhaskell/stack/tree/master/src/test)
-folder. Tests are written using the [Hspec](https://hspec.github.io/) framework. In
-order to run the full test suite, you can simply do:
+be found in the
+[test/integration](https://github.com/commercialhaskell/stack/tree/master/test/integration)
+folder and unit tests, in the
+[src/test](https://github.com/commercialhaskell/stack/tree/master/src/test)
+folder. Tests are written using the [Hspec](https://hspec.github.io/) framework.
+In order to run the full test suite, you can simply do:
 
 ```bash
 $ stack test
@@ -197,13 +303,12 @@ 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.
 
-
 ### Skipping build
 
 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).
+commit message to skip the builds. For more details,
+[refer here](https://github.com/Microsoft/azure-pipelines-agent/issues/858#issuecomment-475768046).
 
 ## Slack channel
 

ChangeLog.md

@@ -1,6 +1,5 @@
 # Changelog
 
-
 ## Unreleased changes
 
 Release notes:
@@ -35,6 +34,9 @@ Other enhancements:
 * Add build option `--cabal-verbosity=VERBOSITY` to specify the Cabal verbosity
   level (the option accepts Cabal's numerical and extended syntax).
   See [#1369](https://github.com/commercialhaskell/stack/issues/809)
+* Add the possibility of a `sh` script to customise fully GHC installation. See
+  [#5585](https://github.com/commercialhaskell/stack/pull/5585)
+* `tools` subcommand added to `stack ls`, to list stack's installed tools.
 
 Bug fixes:
 
@@ -43,6 +45,11 @@ Bug fixes:
 * Fix an inconsistency in the pretty formatting of the output of
   `stack build --coverage`
 * Fix repeated warning about missing parameters when using `stack new`
+* Include `pantry-0.5.6`: Remove operational and mirror keys from bootstrap key
+  set [#53](https://github.com/commercialhaskell/pantry/pull/53)
+* Pass any CPP options specified via `cpp-options:` in the `.cabal` file to GHCi
+  using GHC's `-optP` flag. See
+  [#5608](https://github.com/commercialhaskell/stack/pull/5608) 
 
 ## v2.7.5
 

doc/GUIDE.md

@@ -447,14 +447,17 @@ Remember above when `stack new` selected some
 our build plan and available packages. When we tried using the `text` package,
 it just worked, because it was part of the LTS *package set*.
 
-But `acme-missiles` is not part of that package set, so building failed.
+We've specified the `acme-missiles` package in the `package.yaml` file (see
+above), but `acme-missiles` is not part of that LTS package set, so building
+failed.
 
-To add this new dependency, we'll use the `extra-deps` field in `stack.yaml` to
-define extra dependencies not present in the resolver. You can add this like so:
+To add `acme-missles` to the available packages, we'll use the `extra-deps`
+field in the `stack.yaml` file. That field defines extra packages, not present
+in the resolver, that will be needed as dependencies. You can add this like so:
 
 ```yaml
 extra-deps:
-- acme-missiles-0.3 # not in the LTS
+- acme-missiles-0.3 # not in the LTS resolver
 ```
 
 Now `stack build` will succeed.

doc/yaml_configuration.md

@@ -1198,5 +1198,69 @@ has the following effect:
 
 This field is convenient in setups that restrict access to GitHub, for instance closed corporate setups. In this setting, it is common for the development environment to have general access to the internet, but not for testing/building environments. To avoid the firewall, one can run a local snapshots mirror and then use a custom `snapshot-location-base` in the closed environments only.
 
-
 Since 2.5.0
+
+## Customisation
+
+### GHC installation customisation (experimental)
+
+On Unix-like operating systems and Windows, Stack's installation procedure can
+be fully customised by placing a `sh` shell script (a 'hook') in the Stack root
+directory at `hooks/ghc-install.sh`. On Unix-like operating systems, the script
+file must be made executable. The script is run by the `sh` application (which
+is provided by MSYS2 on Windows).
+
+The script **must** return an exit code of `0` and the standard output **must**
+be the absolute path to the GHC binary that was installed. Otherwise Stack will
+ignore the script and possibly fall back to its own installation procedure.
+
+The script is not run when `system-ghc: true`.
+
+When `install-ghc: false`, the script is still run, which allows you to ensure
+that only your script will install GHC and Stack won't default to its own
+installation logic, even when the script fails.
+
+An example script is:
+
+```sh
+#!/bin/sh
+
+set -eu
+
+case $HOOK_GHC_TYPE in
+	bindist)
+		# install GHC here, not printing to stdout, e.g.:
+		#   command install $HOOK_GHC_VERSION >/dev/null
+		;;
+	git)
+		>&2 echo "Hook doesn't support installing from source"
+		exit 1
+		;;
+	*)
+		>&2 echo "Unsupported GHC installation type: $HOOK_GHC_TYPE"
+		exit 2
+		;;
+esac
+		
+echo "location/to/ghc/executable"
+```
+
+The following environment variables are always available to the script:
+
+* `HOOK_GHC_TYPE = "bindist" | "git" | "ghcjs"`
+
+For "bindist", additional variables are:
+
+* `HOOK_GHC_VERSION = <ver>`
+
+For "git", additional variables are:
+
+* `HOOK_GHC_COMMIT = <commit>`
+* `HOOK_GHC_FLAVOR = <flavor>`
+
+For "ghcjs", additional variables are:
+
+* `HOOK_GHC_VERSION = <ver>`
+* `HOOK_GHCJS_VERSION = <ver>`
+
+Since 2.7.X

etc/scripts/get-stack.sh

@@ -71,9 +71,9 @@ post_install_separator() {
 
 # determines the the CPU's instruction set
 get_isa() {
-  if arch | grep -Eq 'armv[78]l?' ; then
+  if uname -m | grep -Eq 'armv[78]l?' ; then
     echo arm
-  elif arch | grep -q aarch64 ; then
+  elif uname -m | grep -q aarch64 ; then
     echo aarch64
   else
     echo x86

package.yaml

@@ -92,12 +92,15 @@ dependencies:
 - network-uri
 - open-browser
 - optparse-applicative >= 0.14.3.0
-- pantry >= 0.5.3
+- pantry >= 0.5.6
 - casa-client
 - casa-types
 - path
 - path-io
-- persistent
+# In order for Cabal (the tool) to build Stack, it needs to be told of the
+# upper bound on persistent. See
+# https://github.com/commercialhaskell/stack/pull/5677#issuecomment-1193318542 
+- persistent < 2.14
 - persistent-sqlite
 - persistent-template
 - pretty