Acknowledge that stack.yaml is only the default name for the file

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

doc/GUIDE.md

@@ -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
 
@@ -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

@@ -60,8 +60,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
 
@@ -73,9 +73,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
 
@@ -84,7 +84,7 @@ stack config set resolver SNAPSHOT
 ~~~
 
 `stack config set resolver <snapshot>` sets the `resolver` key in the
-project-level configuration file (`stack.yaml`).
+project-level configuration file (`stack.yaml`, by default).
 
 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
@@ -103,7 +103,7 @@ stack config set snapshot SNAPSHOT
 ~~~
 
 `stack config set snapshot <snapshot>` sets the `snapshot` key in the
-project-level configuration file (`stack.yaml`).
+project-level configuration file (`stack.yaml`, by default).
 
 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
@@ -121,5 +121,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

@@ -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)
@@ -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/yaml_configuration.md

@@ -14,9 +14,9 @@ be customised by the use of scripts.
     or dependency located locally.
 
     A Stack project is a local directory that contains a Stack project-level
-    configuration file (`stack.yaml`). A project may relate to more than one
-    project package. A single-package project's directory will usually also be
-    the project package's root directory.
+    configuration file (`stack.yaml`, by default). A project may relate to more
+    than one project package. A single-package project's directory will usually
+    also be the project package's root directory.
 
 ## YAML configuration
 
@@ -405,7 +405,7 @@ curator:
 ## Non-project-specific configuration
 
 Non-project configuration options can be included in a project-level
-configuration file (`stack.yaml`) or in global configuration files
+configuration file (`stack.yaml`, by default) 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.