Merge pull request #4093 from commercialhaskell/stable

Merge stable into master

doc/GUIDE.md

@@ -1613,21 +1613,19 @@ page](https://docs.haskellstack.org/en/stable/shell_autocompletion)
 
 ### Docker
 
-stack provides two built-in Docker integrations. Firstly, you can build your
-code inside a Docker image, which means:
+stack provides two built-in Docker integrations. The first way is to
+build your code inside a Docker image, which means:
 
 * even more reproducibility to your builds, since you and the rest of your team
   will always have the same system libraries
 * the Docker images ship with entire precompiled snapshots. That means you have
   a large initial download, but much faster builds
 
-For more information, see
-[the Docker-integration documentation](docker_integration.md).
-
-stack can also generate Docker images for you containing your built executables.
-This feature is great for automating deployments from CI. This feature is not
-yet well-documented, but the basics are to add a section like the following
-to stack.yaml:
+The second way is to generate Docker images for you containing your
+built executables (the executable is built in your local machine and
+copied into the image) .  This feature is great for automating
+deployments from CI. This feature is not yet well-documented, but the
+basics are to add a section like the following to stack.yaml:
 
 ```yaml
 image:
@@ -1663,9 +1661,10 @@ the images.
 
 Note that the executable will be built in the development environment
 and copied to the container, so the dev OS must match that of the
-container OS. This is easily accomplished using [Docker integration](docker_integration.md),
-under which the exe emitted by `stack build` will be built on the
-Docker container, not the local OS.
+container OS. Note that you can use the `--docker` option to build
+your code inside the Docker container in case you have a different
+development environment or if you specifically want to build on the
+container.
 
 The executable will be stored under `/usr/local/bin/<your-project>-exe`
 in the running container.
@@ -1678,6 +1677,23 @@ entrypoints:
     - <your-project>-exe
 ```
 
+The difference between the first and second integration methods is
+that in the first one your Haskell code is actually built in the
+container whereas in the second one the executable built in your host
+machine is copied to the container. The presence of the following
+configuration in `stack.yaml` informs stack to switch to the first
+integration method:
+
+```yaml
+docker:
+    enable: true
+```
+
+Alternatively, instead of the above configuration, you can use the
+`--docker` option to achieve the same.  You can find more details
+about the first integration method [in the Docker integration
+documentation](./docker_integration.md).
+
 ### Nix
 
 stack provides an integration with [Nix](http://nixos.org/nix),
@@ -1817,7 +1833,7 @@ There are lots of resources available for learning more about stack:
 * `--verbose` (or `-v`) — much more info about internal operations (useful for bug reports)
 * The [home page](http://haskellstack.org)
 * The [stack mailing list](https://groups.google.com/d/forum/haskell-stack)
-* The [the FAQ](faq.md)
+* The [FAQ](faq.md)
 * The [stack wiki](https://github.com/commercialhaskell/stack/wiki)
 * The [haskell-stack tag on Stack Overflow](http://stackoverflow.com/questions/tagged/haskell-stack)
 * [Another getting started with stack tutorial](http://seanhess.github.io/2015/08/04/practical-haskell-getting-started.html)

doc/appveyor.yml

@@ -12,8 +12,21 @@ environment:
   global:
     STACK_ROOT: "c:\\sr"
 
+  matrix:
+  - ARGS: ""
+  #- ARGS: "--resolver lts-2"
+  #- ARGS: "--resolver lts-3"
+  #- ARGS: "--resolver lts-6"
+  #- ARGS: "--resolver lts-7"
+  - ARGS: "--resolver lts-9"
+  - ARGS: "--resolver lts-11"
+  #- ARGS: "--resolver nightly"
+
 test_script:
-- stack setup > nul
+
+# Install toolchain, but do it silently due to lots of output
+- stack %ARGS% setup > nul
+
 # The ugly echo "" hack is to avoid complaints about 0 being an invalid file
 # descriptor
-- echo "" | stack --no-terminal test
+- echo "" | stack %ARGS% --no-terminal test --pedantic

doc/architecture.md

@@ -96,7 +96,7 @@ installed executables, since GHC does not track them for us.
 
 When running a build, we know which packages we want installed (inventively
 called "wanteds"), which packages are available to install, and which are
-already installed. In plan construction, we put them information together to
+already installed. In plan construction, we put this information together to
 decide which packages must be built. The code in Stack.Build.ConstructPlan is
 authoritative on this and should be consulted. The basic idea though is:
 

doc/install_and_upgrade.md

@@ -73,7 +73,7 @@ Run:
 
 If you have the popular [brew](https://brew.sh/) tool installed, you can just do:
 
-    brew install haskell-stack
+    brew install stack
 
 * The Homebrew formula and bottles are **unofficial** and lag slightly behind new Stack releases,
 but tend to be updated within a day or two.

doc/MAINTAINER_GUIDE.md → doc/maintainers/releases.md

@@ -1,6 +1,6 @@
 <div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://rawgit.com/commercialhaskell/stack/master/doc/img/hidden-warning.svg"></a></div>
 
-# Maintainer guide
+# Releases
 
 ## Next release:
 
@@ -437,3 +437,33 @@ GHC 7.8.4 is slightly different:
     sed -i 's/^TAR_COMP *= *bzip2$/TAR_COMP = xz/' mk/config.mk && \
     make -j$(cat /proc/cpuinfo|grep processor|wc -l) && \
     make binary-dist
+
+## Upgrading msys
+
+When installing GHC on Windows, Stack will also install
+[msys2](http://www.msys2.org/) to provide a Unix shell and environment,
+necessary for such things as running configure scripts. This section explains
+the steps required to upgrade the msys2 version used by Stack.
+
+1.  Download latest installers from msys2's website. These installers are
+    executables, versioned by date (YYYYMMDD), and are separate for `x86_64`
+    and `i686`. You'll usually be upgrading both at the same time, which we'll
+    assume here.
+
+2.  Run the installer and install to the default location (`c:\msys64` and
+    `c:\msys32`, respectively).
+
+3.  Create tarballs for each directory:
+
+    ```
+    $ cd /c/
+    $ tar cJf msys2-YYYYMMDD-x86_64.tar.xz msys64
+    $ tar cJf msys2-YYYYMMDD-i686.tar.xz msys32
+    ```
+
+4.  Create a new release named `msys2-YYYYMMDD` on the
+    [fpco/stackage-content](https://github.com/fpco/stackage-content)
+    repo, and upload these two files.
+
+5.  Create a PR for the [stack-setup-2.yaml file](https://github.com/fpco/stackage-content/blob/master/stack/stack-setup-2.yaml)
+    to switch over to using the newly uploaded files. You should test this file locally first.

doc/maintainers/team_process.md

@@ -0,0 +1,185 @@
+<div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://rawgit.com/commercialhaskell/stack/master/doc/img/hidden-warning.svg"></a></div>
+
+# Stack Maintainer Team Process
+
+## Purpose of this document
+
+This guide is intended to formalize the process by which the `Stack` maintainer
+team operates. We expect it'll evolve over time as experience makes clearer
+what works best in practice.
+
+Having a well-documented set of processes and responsibilities has been
+instrumental in effectively maintaining the `Stackage` project across a
+distributed team
+([see the `Stackage` curators' guide
+](https://github.com/commercialhaskell/stackage/blob/master/CURATORS.md))
+and we hope to replicate that success here.
+
+
+## Goals
+
+The goals of the `Stack` maintainer team are to:
+
+- Ensure that incoming bug reports and feature requests are properly triaged,
+  answered, and/or escalated.
+
+- Provide timely review of, and feedback on, incoming pull requests.
+
+- Set up clear channels of communication for users to make support requests.
+
+- Keep Stack up-to-date with its upstream dependencies, including new GHC and
+  Cabal releases, and libraries Stack depends on.
+
+- Increase the [bus factor](https://en.wikipedia.org/wiki/Bus_factor) of the
+  project, encouraging more people to contribute heavily to the codebase and
+  take ownership of it.
+
+- Make it easy to improve the documentation and test coverage of the project.
+
+The sections below detail various activities by the `Stack` team to realize
+these goals.
+
+
+## Issue triage
+
+The maintainer team provides ongoing review and responses to newly-filed GitHub
+issues and pull requests. From experience, we find it's easiest to have a
+single person "on call" at any given time. Therefore, the team rotates shifts
+on a weekly basis. The "on call" triager is responsible for:
+
+- Reviewing incoming issues and pull requests on GitHub.
+
+- Answering questions he/she is able to.
+
+- Merging PRs he/she feels comfortable reviewing.
+
+- Closing out irrelevant/misplaced issues.
+
+- Pulling in another maintainer to assist if necessary.
+
+The goal of the triager role is to facilitate continual, smooth progress of
+`Stack`'s development and to provide triagers an opportunity to become more
+familiar with how the project runs.
+
+This is one path to getting a lot of experience with the codebase, plus great
+interaction with the rest of the maintainer team, without necessarily taking on
+major coding tasks.
+
+
+## Time commitment
+
+Someone considering joining the issue triager team may be wondering:
+
+> "How large of a time investment is necessary?"
+
+That’s a great question for anyone considering taking on this role. It’s
+frankly somewhat uncertain right now since we’re only getting started, but we
+can venture a reasonable guess:
+
+We currently average about one new issue per day. Assuming that each issue
+entails roughly ten-to-fifteen minutes of total interaction on the part of the
+triager (before passing it off to someone else, answering a support question,
+etc) that amounts to about one or two hours spent per week being on-call.
+
+Again, these estimates will evolve over time as we settle into an optimal
+process, but for now we anticipate growing the team to about eight members
+(which is the size of the `Stackage` team as well), each of whom is likely to
+spend about two hours in total on upkeep work every eight weeks. 
+
+
+## Issue and pull request interaction guidelines
+
+These guidelines apply to all members of the maintainer team.
+
+- Be courteous.
+
+- Avoid leaving issues and PRs in an ambiguous state. By default, when you
+  respond to an issue/PR, you’re taking responsibility for shepherding it to
+  completion. Be explicit if you’re passing it to someone else, or asking the
+  submitter for more info/updates/etc.
+
+- Use labels, assignees, and milestones wherever possible.
+
+- If you know you’ll be unable to answer for a significant period of time, say
+  so. Even better: ask someone else to take over from you.
+
+
+## Assessing feature requests and enhancement PRs
+
+**NB: this section is very likely to evolve over time as well.**
+
+A frequent source of new GitHub issues is users who would like to propose some
+enhancement and/or change to how `Stack` currently operates.
+
+Some of these are both small and obviously beneficial, in which case the
+triager should feel empowered to "green light" the idea if it makes sense to do
+so.
+
+If the proposal is already in the form of an actionable PR the triager may
+review and merge at their discretion.
+
+Oftentimes though, the request is larger and more far-reaching in nature.
+
+Perhaps the requester is unaware of the extent to which his or her change would
+impact other people's workflows or related components in the code. Conversely,
+they may have a deep understanding of its implications and feel strongly that
+it would be a valuable improvement, whereas it's not so clear to the triager.
+
+Discerning which requests should be considered "small" and which warrant
+broader collaboration is admittedly an inexact science. Use your best judgment
+and don't sweat the occasional mistake if you approve something you thought was
+small but ultimately wasn't.
+
+In the case of medium-to-large sized feature requests, it's best to solicit
+feedback from at least one or two of the core `Stack` developers. You may use
+GitHub @mentions to draw the relevant contributors' attention to the issue in
+question. If you're not sure who's best to consult you should ask on
+`#stack-collaborators`.
+
+Try to be clear to the requester that you're opening the discussion up to more
+participants and that the proposal will require thoughtful consideration
+(probably a majority vote) before any decision is made. 
+
+Also remember that busy schedules, lack of complete familiarity with a given
+subject, strong-yet-opposing opinions held by equally rational people, and many
+other factors often collude to halt forward progress in arriving at firm
+conclusions in such situations... If at all possible, try to keep things
+on-track and concrete.
+
+*Regardless of feature size, bear in mind that sometimes the best answer is a
+respectful "no".*
+
+*If feasible, propose alternative solutions or educate the user in preference to
+complicating `Stack` or accepting scope-creep.* 
+
+With respect to assessing a PR's code, @snoyberg has outlined some
+[tips for successfully getting one's work merged
+](https://www.snoyman.com/blog/2017/06/how-to-send-me-a-pull-request)
+into his projects which may be helpful to `Stack` triagers when performing
+reviews, as well.
+
+
+## Real-time communications
+
+At present, the maintainer team mostly communicates via a rather quiet channel
+called [`#stack-collaborators`](../CONTRIBUTING/#slack-channel) on FP
+Complete's Slack workspace, although we may migrate to some other platform in
+the near future.
+
+
+## Dealing with support issues
+
+We encourage users to submit support requests via GitHub issues and try to
+consolidate our efforts in addressing questions there. Other platforms, such as
+Reddit, StackOverflow, et al, may be helpful as well but the `Stack`
+maintainers team makes no guarantees about regularly checking them.
+
+*We may decide to offload support questions elsewhere in the future, but for
+now the most important thing is to direct users to a single destination.*
+
+
+## Old issue closing policy
+
+We have yet to settle on a precise guide for closing out old issues, but, for
+now, if you happen across something that could easily be marked as resolved,
+please do so.

doc/travis-complex.yml

@@ -60,9 +60,9 @@ matrix:
   - env: BUILD=cabal GHCVER=8.2.2 CABALVER=2.0 HAPPYVER=1.19.5 ALEXVER=3.1.7
     compiler: ": #GHC 8.2.2"
     addons: {apt: {packages: [cabal-install-2.0,ghc-8.2.2,happy-1.19.5,alex-3.1.7], sources: [hvr-ghc]}}
-  - env: BUILD=cabal GHCVER=8.4.1 CABALVER=2.0 HAPPYVER=1.19.5 ALEXVER=3.1.7
-    compiler: ": #GHC 8.4.1"
-    addons: {apt: {packages: [cabal-install-2.0,ghc-8.4.1,happy-1.19.5,alex-3.1.7], sources: [hvr-ghc]}}
+  - env: BUILD=cabal GHCVER=8.4.3 CABALVER=2.2 HAPPYVER=1.19.5 ALEXVER=3.1.7
+    compiler: ": #GHC 8.4.3"
+    addons: {apt: {packages: [cabal-install-2.2,ghc-8.4.3,happy-1.19.5,alex-3.1.7], sources: [hvr-ghc]}}
 
   # Build with the newest GHC and cabal-install. This is an accepted failure,
   # see below.

doc/yaml_configuration.md

@@ -199,6 +199,8 @@ will clone that repo.
 extra-deps:
 - git: git@github.com:commercialhaskell/stack.git
   commit: 6a86ee32e5b869a877151f74064572225e1a0398
+- git: git@github.com:snoyberg/http-client.git
+  commit: "a5f4f3"
 - hg: https://example.com/hg/repo
   commit: da39a3ee5e6b4b0d3255bfef95601890afd80709
 ```
@@ -226,6 +228,14 @@ extra-deps:
   - wai
 ```
 
+Since v1.7.1, you can specify packages from GitHub repository name using `github`:
+
+```yaml
+extra-deps:
+- github: snoyberg/http-client
+  commit: a5f4f30f01366738f913968163d856366d7e0342
+```
+
 If unspecified, `subdirs` defaults to `['.']` meaning looking for a
 package in the root of the repo..  Note that if you specify a value of
 `subdirs`, then `'.'` is _not_ included by default and needs to be
@@ -956,7 +966,7 @@ This option specifies additional directories to prepend to the PATH environment
 variable.  These will be used when resolving the location of executables, and
 will also be visible in the `PATH` variable of processes run by stack.
 
-For example, to prepend `/path-to-some-dep/bin` to your PATh:
+For example, to prepend `/path-to-some-dep/bin` to your PATH:
 
 ```yaml
 extra-path:

etc/dockerfiles/stack-build/lts-11.6/Dockerfile

@@ -0,0 +1,3 @@
+FROM fpco/stack-build:lts-11.5
+ARG STACK_VERSION=1.7.1
+RUN wget -qO- https://github.com/commercialhaskell/stack/releases/download/v$STACK_VERSION/stack-$STACK_VERSION-linux-x86_64.tar.gz | tar xz --wildcards --strip-components=1 -C /usr/local/bin '*/stack'