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.
 

doc/lock_files.md

@@ -39,7 +39,7 @@ they are created and updated.
 ## stack.yaml and snapshot files
 
 Relevant to this discussion, Stack's project-level configuration file
-(`stack.yaml`) specifies:
+(`stack.yaml`, by default) specifies:
 
 * the parent snapshot (the [`snapshot`](yaml_configuration.md#snapshot) or
   [`resolver`](yaml_configuration.md#resolver) key)
@@ -103,7 +103,7 @@ common case of no changes.
 
 The lock file contains the following information:
 
-* Completed package locations for extra deps and packages in snapshot files
+* Completed package locations for extra-deps and packages in snapshot files
 
     !!! note
 
@@ -148,9 +148,9 @@ packages:
 
 ## Creation procedure
 
-Whenever a project-level configuration file (`stack.yaml`) is loaded, Stack
-checks for a lock file in the same file path, with a `.lock` extension added.
-For example, if you command:
+Whenever a project-level configuration file (`stack.yaml`, by default) is
+loaded, Stack checks for a lock file in the same file path, with a `.lock`
+extension added. For example, if you command:
 
 ~~~text
 stack --stack-yaml my-stack.yaml build
@@ -177,9 +177,9 @@ created by:
 
 ## Update procedure
 
-Whenever a project-level configuration file (`stack.yaml`) is loaded, all
-completed package or snapshot locations (even those completed using information
-from a lock file) get collected to form a new lock file in memory. Subject to
-Stack's [`--lock-file`](global_flags.md#-lock-file-option) option, that new lock
-file is compared against the one on disk and, if there are any differences,
-written out to the disk.
+Whenever a project-level configuration file (`stack.yaml`, by default) is
+loaded, all completed package or snapshot locations (even those completed using
+information from a lock file) get collected to form a new lock file in memory.
+Subject to Stack's [`--lock-file`](global_flags.md#-lock-file-option) option,
+that new lock file is compared against the one on disk and, if there are any
+differences, written out to the disk.

doc/nix_integration.md

@@ -311,7 +311,7 @@ Stack expects the `shell.nix` file to define a function of with one argument
 called `ghc` (arguments are not positional), which you should give to
 function `buildStackProject`. This argument is a GHC Nix package in the
 version as defined in the snapshot you set in Stack's project-level
-configuration file (`stack.yaml`).
+configuration file (`stack.yaml`, by default).
 
 ### Pure and impure Nix shells
 
@@ -377,7 +377,8 @@ set.
 
 Below is a summary of the non-project specific configuration options and their
 default values. The options can be set in Stack's project-level configuration
-file (`stack.yaml`) or its global configuration file (`config.yaml`).
+file (`stack.yaml`, by default) or its global configuration file
+(`config.yaml`).
 
 ~~~yaml
 nix:

doc/nonstandard_project_init.md

@@ -3,7 +3,8 @@
 # Non-standard project initialization
 
 You may need to configure Stack to work with an existing project that has one or
-more Cabal files but no Stack project-level configuration file (`stack.yaml`).
+more Cabal files but no Stack project-level configuration file (`stack.yaml`, by
+default).
 
 ## The `stack init` command
 

doc/path_command.md

@@ -22,7 +22,7 @@ Pass the following flags for information about specific files or locations:
 |--compiler-bin         |The directory containing the GHC executable.          |
 |--compiler-exe         |The GHC executable.                                   |
 |--compiler-tools-bin   |The directory containing binaries specific to a particular compiler.|
-|--config-location      |Stack's project-level YAML configuration file (`stack.yaml`).|
+|--config-location      |Stack's project-level YAML configuration file (`stack.yaml`, by default).|
 |--dist-dir             |The dist work directory, relative to the package directory.|
 |--extra-include-dirs   |Extra include directories.                            |
 |--extra-library-dirs   |Extra library directories.                            |

doc/script_command.md

@@ -138,17 +138,17 @@ LTS Haskell 20.25, where considerations on Windows differ from non-Windows. The
     ~~~
 
     `acme-missiles` is not in the snapshot and so needs to be specified as an
-    extra dep.
+    extra-dep.
 
     Stack can deduce that the module imports imply that the required packages
     are `acme-missiles`, `time` and `extra` (which is in the snapshot).
 
     `extra` depends on `directory` and `process`. If `directory` and `process`
-    are not specified as extra deps, Stack will complain that they have been
+    are not specified as extra-deps, Stack will complain that they have been
     'pruned'.
 
     `directory-1.3.6.2` depends on `time < 1.12`. If `time` is not specified as
-    an extra dep, Stack will try to construct a build plan based on the latest
+    an extra-dep, Stack will try to construct a build plan based on the latest
     version in the package index (which will fail, as the latest version is
     `>= 1.12`)
 
@@ -168,7 +168,7 @@ LTS Haskell 20.25, where considerations on Windows differ from non-Windows. The
     ~~~
 
     `acme-missiles` is not in the snapshot and so needs to be specified as an
-    extra dep.
+    extra-dep.
 
     Stack can deduce that the module imports imply that the required packages
     are `acme-missiles`, `time` and `extra` (which is in the snapshot).

doc/stack_yaml_vs_cabal_package_file.md

@@ -50,14 +50,14 @@ Stack defines a new concept called a _project_. A project has:
 * And a bunch more Stack configuration
 
 Often you will have a project that defines only one local Cabal package that you
-are working on. If you need to specify an extra dependency, a source of
-confusion can be why you need to specify it both in the `stack.yaml` file _and_
+are working on. If you need to specify a dependency, a source of confusion can
+be why you need to specify it both in the `stack.yaml` file _and_
 in the Cabal file. To explain, let's take a quick detour to talk about snapshots
 and how Stack resolves dependencies.
 
 ## Snapshots and resolvers
 
-Stack follows a rule that says, for any projects, there is precisely one version
+Stack follows a rule that says, for any project, there is precisely one version
 of each package available. Obviously, for many packages there are _many_
 versions available in the world. But when resolving a `stack.yaml` file, Stack
 requires that you have chosen a specific version for each package available.