Merge branch 'stable'

Author: mpilgrem

CONTRIBUTING.md

@@ -549,8 +549,8 @@ The `pedantic` job runs on `ubuntu` only and builds Stack with the
 `--pedantic` flag.
 
 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`.
+project-level YAML configuration files (`stack.yaml`, by default). 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

ChangeLog.md

@@ -279,7 +279,7 @@ Bug fixes:
 Hackage-only release of the `stack` package:
 
 * Supports building against snapshot Stackage LTS Haskell 21.0 (GHC 9.4.5),
-  without extra deps.
+  without extra-deps.
 * Supports build with `persistent-2.14.5.0`, using CPP directives.
 * Supports build with `unix-compat-0.7`, by removing reliance on the module
   `System.PosixCompat.User` removed in that package.
@@ -1650,7 +1650,7 @@ Bug fixes:
 * `stack script` can now handle relative paths to source files.
   See [#3372](https://github.com/commercialhaskell/stack/issues/3372).
 * Fixes explanation of why a target is needed by the build plan, when the
-  target is an extra dependency from the commandline.
+  target is an extra-dep from the commandline.
   See [#3378](https://github.com/commercialhaskell/stack/issues/3378).
 * Previously, if you delete a yaml file from ~/.stack/build-plan, it would
   trust the etag and not re-download.  Fixed in this version.
@@ -2480,8 +2480,8 @@ Major changes:
     * Overall it should now be able to initialize almost all existing Cabal
       packages out of the box as long as the package itself is consistently
       defined.
-    * Choose the best possible snapshot and add extra dependencies on top
-      of a snapshot resolver rather than a compiler resolver -
+    * Choose the best possible snapshot and add extra-deps on top
+      of a snapshot other than a compiler snapshot -
       [#1583](https://github.com/commercialhaskell/stack/pull/1583)
     * Automatically omit a package (`--omit-packages`) when it is compiler
       incompatible or when there are packages with conflicting dependency
@@ -2948,7 +2948,7 @@ Bug fixes:
 
 * Hacky workaround for optparse-applicative issue with `stack exec --help`
   [#806](https://github.com/commercialhaskell/stack/issues/806)
-* Build executables for local extra deps
+* Build executables for local extra-deps
   [#920](https://github.com/commercialhaskell/stack/issues/920)
 * copyFile can't handle directories
   [#942](https://github.com/commercialhaskell/stack/pull/942)

doc/GUIDE.md

@@ -1337,7 +1337,7 @@ followed by the module name.
 !!! note
 
     If you have added packages to your project please make sure to mark them as
-    extra deps for faster and reliable usage of `stack ghci`. Otherwise GHCi may
+    extra-deps for faster and reliable usage of `stack ghci`. Otherwise GHCi may
     have trouble due to conflicts of compilation flags or having to
     unnecessarily interpret too many modules. See Stack's project-level
     [configuration](yaml_configuration.md#extra-deps) to learn how to
@@ -1424,10 +1424,10 @@ Cabal (the tool), and NixOS. In that sense, we're sharing the same ecosystem.
 ### Curation vs dependency solving
 
 * Stack uses 'curation' (snapshots and Stack's project-level configuration file
-  (`stack.yaml`) define precisely the set of packages available for a project).
-  The Stack team firmly believes that the majority of users want to simply
-  ignore dependency resolution nightmares and get a valid build plan from day
-  one. That's why we've made 'curation' the focus of Stack.
+  (`stack.yaml`, by default) define precisely the set of packages available for
+  a project). The Stack team firmly believes that the majority of users want to
+  simply ignore dependency resolution nightmares and get a valid build plan from
+  day one. That's why we've made 'curation' the focus of Stack.
 
 * Cabal (the tool) can use 'curation' too but its origins are in dependency
   solving.

doc/azure_ci.md

@@ -131,10 +131,10 @@ But we only use the first method of using Stack to download GHC.
 ### Multiple GHC - parametrised builds
 
 For different GHC versions, you probably want to use different project-level
-configuration files (`stack.yaml`). If you don't want to put a specific
-`stack.yaml` for a particular snapshot and still want to test it, you have
-specify your snapshot argument in `ARGS` environment variable (you will see an
-example below).
+configuration files (`stack.yaml`, by default). If you don't want to put a
+specific `stack.yaml` for a particular snapshot and still want to test it, you
+have specify your snapshot argument in `ARGS` environment variable (you will see
+an example below).
 
 ~~~yaml
 strategy:

doc/build_command.md

@@ -67,7 +67,7 @@ This ability to specify a component applies only to a project package. With
 dependencies, Stack will *always* build the library (if present) and all
 executables (if any), and ignore test suites and benchmarks. If you want more
 control over a package, you must add it to your `packages` setting in your
-project-level configuration file (`stack.yaml`).
+project-level configuration file (`stack.yaml`, by default).
 
 ## Target syntax
 
@@ -76,9 +76,9 @@ supported syntaxes for targets are:
 
 *   *package*, e.g. `stack build foobar`, is the most commonly used target. It
     will try to find the package in the following locations: project packages,
-    extra deps, snapshots, and package index (e.g. Hackage). If it's found in
-    the package index, then the latest version of that package from the index is
-    implicitly added to your extra dependencies.
+    extra-deps, the snapshot, and the package index (e.g. Hackage). If it's
+    found in the package index, then the latest version of that package from the
+    index is implicitly added as an extra-dep.
 
     If the package is a project package, the library and executable components
     are selected to be built. If the `--test` and `--bench` flags are set, then
@@ -813,7 +813,7 @@ Examples:
     index into a local project directory named after the package identifier (for
     further infomation, see the [`stack unpack` command](unpack_command.md)
     documentation) and, if the package does not provide its own Stack
-    configuration file (`stack.yaml`), to attempt to initialise that
+    configuration file (`stack.yaml`, by default), to attempt to initialise that
     configuration (for further information, see the
     [`stack init` command](init_command.md) documentation). For example:
 

doc/config_command.md

@@ -61,8 +61,8 @@ stack config set install-ghc [--global] true|false
 
 `stack config set install-ghc true` or `false` sets the `install-ghc` key in a
 YAML configuration file, accordingly. By default, the project-level
-configuration file (`stack.yaml`) is altered. The `--global` flag specifies the
-user-specific global configuration file (`config.yaml`).
+configuration file (`stack.yaml`, by default) is altered. The `--global` flag
+specifies the user-specific global configuration file (`config.yaml`).
 
 ## The `stack config set package-index download-prefix` command
 
@@ -74,9 +74,9 @@ stack config set package-index download-prefix [--global] [URL]
 
 `stack config set package-index download-prefix <url>` sets the
 `download-prefix` key of the `package-index` key in a YAML configuration file,
-accordingly. By default, the project-level configuration file (`stack.yaml`) is
-altered. The `--global` flag specifies the user-specific global configuration
-file (`config.yaml`).
+accordingly. By default, the project-level configuration file (`stack.yaml`, by
+default) is altered. The `--global` flag specifies the user-specific global
+configuration file (`config.yaml`).
 
 ## The `stack config set resolver` command
 
@@ -97,7 +97,8 @@ stack config set snapshot SNAPSHOT
 ~~~
 
 `stack config set snapshot <snapshot>` sets the `snapshot` key in the
-project-level configuration file (`stack.yaml`) to the specified snapshot.
+project-level configuration file (`stack.yaml`, by default) to the specified
+snapshot.
 
 A snapshot of `lts` or `nightly` will be translated into the most recent
 available. A snapshot of `lts-22` will be translated into the most recent
@@ -113,5 +114,5 @@ stack config set system-ghc [--global] true|false
 
 `stack config set system-ghc true` or `false` sets the `system-ghc` key in a
 YAML configuration file, accordingly. By default, the project-level
-configuration file (`stack.yaml`) is altered. The `--global` flag specifies the
-user-specific global configuration file (`config.yaml`).
+configuration file (`stack.yaml`, by default) is altered. The `--global` flag
+specifies the user-specific global configuration file (`config.yaml`).

doc/dev_containers.md

@@ -9,8 +9,8 @@ development environment.
 
 Stack provides the following Dev Containers:
 
-* a default Dev Container, intended for use with Stack's project‑level
-  configuration (`stack.yaml`); and
+* a default Dev Container, intended for use with Stack's default project‑level
+  configuration file (`stack.yaml`); and
 * alternative Dev Containers, intended for use with Stack's experimental
   project‑level configurations (in anticipation of building Stack with more
   recent versions of GHC).

doc/faq.md

@@ -14,8 +14,8 @@ the _snapshot_. This may be something like `lts-22.7`, which is from
 the snapshot in more detail.
 
 The snapshot is determined by finding the relevant project-level configuration
-file (`stack.yaml`) for the directory you're running the command from. This
-essentially works by:
+file (`stack.yaml`, by default) for the directory you're running the command
+from. This essentially works by:
 
 1. Check for a `STACK_YAML` environment variable or the `--stack-yaml`
    command line argument
@@ -298,8 +298,8 @@ of those three. Updating the index will have no impact on Stack's behavior.
 
 ## I have a custom package index I'd like to use, how do I do so?
 
-You can configure this in your project-level configuration file (`stack.yaml`).
-See [YAML configuration](yaml_configuration.md).
+You can configure this in your project-level configuration file (`stack.yaml`,
+by default). See [YAML configuration](yaml_configuration.md).
 
 ## How can I make sure my project builds against multiple GHC versions?
 

doc/glossary.md

@@ -15,7 +15,7 @@ The following terms are used in Stack's documentation.
 |dependency         |A Haskell package other than a project package and on which a project package depends (directly or indirectly), located locally or elsewhere.|
 |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 (one version of each) that add to, or amend, those specified in a snapshot. Named after a key used in `stack.yaml` files.|
+|extra-deps         |Extra dependencies (one version of each) that add to, or shadow, those specified in a snapshot.|
 |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/).|
@@ -41,7 +41,7 @@ The following terms are used in Stack's documentation.
 |`package.yaml`     |A file that describes a package in the Hpack format.      |
 |Pantry             |A library for content-addressable Haskell package management, provided by the [`pantry` package](https://hackage.haskell.org/package/pantry). A dependency of Stack.|
 |PATH               |The `PATH` environment variable, specifying a list of directories searched for executable files.|
-|project            |A Stack project is a local directory that contains a project-level configuration file (`stack.yaml`). A project may relate to more than one project package.|
+|project            |A Stack project is a local directory that contains a project-level configuration file (`stack.yaml`, by default). A project may relate to more than one project package.|
 |project package    |A Haskell package that is part of a project and located locally. Distinct from a dependency located locally.|
 |PVP                |The Haskell [Package Versioning Policy](https://pvp.haskell.org/), which tells developers of libraries how to set their version numbers.|
 |REPL               |An interactive (run-eval-print loop) programming environment.|

doc/init_command.md

@@ -6,7 +6,7 @@
 stack init [DIR(S)] [--omit-packages] [--force] [--ignore-subdirs]
 ~~~
 
-`stack init` initialises Stack's project-level YAML configuration file
+`stack init` initialises Stack's default project-level YAML configuration file
 (`stack.yaml`) for an existing project, based on the Cabal file or
 `package.yaml` file for each of its packages.