Merge branch 'stable'

Author: mpilgrem

doc/glossary.md

@@ -14,7 +14,7 @@ The following terms are used in Stack's documentation.
 |`config.yaml`      |A global and non-project-specific configuration file used by Stack.|
 |Docker             |A [platform](https://www.docker.com/) for developing,  shipping, and running applications. It can package and run an application in a loosely isolated environment called a _container_.|
 |Emacs              |[GNU Emacs](https://www.gnu.org/software/emacs/), an extensible, customisable text editor.|
-|extra-deps         |Packages in addition to those in a snapshot, named after a key used in `stack.yaml` files.|
+|extra-deps         |Packages (one version of each) that add to, or amend, those specified in a snapshot. Named after a key used in `stack.yaml` files.|
 |FreeBSD            |A Unix-like operating system.                             |
 |GCC                |The [GNU Compiler Collection](https://gcc.gnu.org/) or its executable `gcc`.|
 |GHC                |The [Glasgow Haskell Compiler](https://www.haskell.org/ghc/).|
@@ -43,7 +43,7 @@ The following terms are used in Stack's documentation.
 |REPL               |An interactive (run-eval-print loop) programming environment.|
 |resolver           |A synonym for snapshot.                                   |
 |`Setup.hs`         |A project-specific file used by Cabal to perform setup tasks.|
-|snapshot           |A snapshot defines a GHC version, a set of packages, and build flags or other settings.|
+|snapshot           |A snapshot defines a GHC version, a set of packages (one version of each), and build flags or other settings.|
 |Stack              |The Haskell Tool Stack project or its executable `stack`. |
 |`stack.yaml`       |A project-level configuration file used by Stack, which may also contain non-project-specific options.|
 |Stackage           |A [distribution](https://www.stackage.org/) of compatible Haskell packages.|

doc/yaml_configuration.md

@@ -13,7 +13,9 @@ Stack's YAML configuration options break down into
 configured at the project-level or globally.
 
 The **project-level** configuration file (`stack.yaml`) contains
-project-specific options and may contain non-project-specific options.
+project-specific options and may contain non-project-specific options. However,
+non-project-specific options in the project-level configuration file in the
+`global-project` directory (see below) are ignored by Stack.
 
 Stack obtains project-level configuration from one of the following (in order of
 preference):
@@ -301,8 +303,10 @@ TODO: Add a simple example of how to use custom preprocessors.
 
 ## Non-project-specific configuration
 
-Non-project configuration options are valid in a project-level configuration
-file (`stack.yaml`) or in global configuration files (`config.yaml`). The
+Non-project configuration options can be included in a project-level
+configuration file (`stack.yaml`) or in global configuration files
+(`config.yaml`). However, non-project-specific options in the project-level
+configuration file in the `global-project` directory are ignored by Stack. The
 options below are listed in alphabetic order.
 
 ### allow-different-user