commercialhaskell · snoyberg · Jul 17, 2017 · Apr 12, 2017 · Apr 12, 2017 · Apr 19, 2017
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -7,10 +7,10 @@ and use the provided template to include all necessary details.
 
 The more detailed your report, the faster it can be resolved and will ensure it
 is resolved in the right way. Once your bug has been resolved, the responsible
-will tag the issue as _Needs confirmation_ and assign the issue back to you.
-Once you have tested and confirmed that the issue is resolved, close the issue.
-If you are not a member of the project, you will be asked for confirmation and
-we will close it.
+person will tag the issue as _Needs confirmation_ and assign the issue back to
+you. Once you have tested and confirmed that the issue is resolved, close the 
+issue. If you are not a member of the project, you will be asked for
+confirmation and we will close it.
 
 
 ## Documentation

diff --git a/ChangeLog.md b/ChangeLog.md
@@ -6,6 +6,12 @@ Release notes:
 
 Major changes:
 
+* Complete overhaul of how snapshots are defined, the `packages` and
+  `extra-deps` fields, and a number of related items. For full
+  details, please see
+  [the writeup on these changes](https://www.fpcomplete.com/blog/2017/07/stacks-new-extensible-snapshots). [PR #3249](https://github.com/commercialhaskell/stack/pull/3249),
+  see the PR description for a number of related issues.
+
 Behavior changes:
 
 * `stack profile` and `stack trace` now add their extra RTS arguments for
@@ -37,9 +43,40 @@ Other enhancements:
 * `--[no-]haddock-hyperlink-source` flag added which allows toggling
   of sources being included in Haddock output.
   See [#3099](https://github.com/commercialhaskell/stack/issues/3099)
+* `stack ghci` will now skip building all local targets, even if they have
+  downstream deps, as long as it's registered in the DB.
+* The pvp-bounds feature now supports adding `-revision` to the end of
+  each value, e.g. `pvp-bounds: both-revision`. This means that, when
+  uploading to Hackage, Stack will first upload your tarball with an
+  unmodified `.cabal` file, and then upload a cabal file revision with
+  the PVP bounds added. This can be useful&mdash;especially combined
+  with the
+  [Stackage no-revisions feature](http://www.snoyman.com/blog/2017/04/stackages-no-revisions-field)&mdash;as
+  a method to ensure PVP compliance without having to proactively fix
+  bounds issues for Stackage maintenance.
+* Expose a `save-hackage-creds` configuration option
+* On GHC <= 7.8, filters out spurious linker warnings on windows
+  See [#3127](https://github.com/commercialhaskell/stack/pull/3127)
+* Better error messages when creating or building packages which alias
+  wired-in packages. See
+  [#3172](https://github.com/commercialhaskell/stack/issues/3172).
+* MinGW bin folder now is searched for dynamic libraries. See [#3126](https://github.com/commercialhaskell/stack/issues/3126)
+* When using Nix, nix-shell now depends always on git to prevent runtime errors
+  while fetching metadata
+* The `stack unpack` command now accepts a form where an explicit
+  Hackage revision hash is specified, e.g. `stack unpack
+  foo-1.2.3@gitsha1:deadbeef`. Note that this should be considered
+  _experimental_, Stack will likely move towards a different hash
+  format in the future.
+* `GitSHA1` is now `StaticSHA256` and is implemented using the `StaticSize 64 ByteString` for improved performance.
+  See [#3006](https://github.com/commercialhaskell/stack/issues/3006)
 
 Bug fixes:
 
+* Building all executables only happens once instead of every
+  time. See
+  [#3229](https://github.com/commercialhaskell/stack/issues/3229) for
+  more info.
 * Fixes case where `stack build --profile` might not cause executables /
   tests / benchmarks to be rebuilt.
   See [#2984](https://github.com/commercialhaskell/stack/issues/2984)
@@ -56,7 +93,17 @@ Bug fixes:
   package database for wired-in-packages (ghc, base, etc).
   See [#3084](https://github.com/commercialhaskell/stack/issues/3084)
 * Fixes `stack --docker build` when user is part of libvirt/libvirtd
-  groups on Ubuntu Yakkety (16.10). See [#3092]
+  groups on Ubuntu Yakkety (16.10).
+  See [#3092](https://github.com/commercialhaskell/stack/issues/3092)
+* Switching a package between extra-dep and local package now forces
+  rebuild (previously it wouldn't if versions were the same).
+  See [#2147](https://github.com/commercialhaskell/stack/issues/2147)
+* `stack upload` no longer reveals your password when you type it on
+  MinTTY-based Windows shells, such as Cygwin and MSYS2.
+  See [#3142](https://github.com/commercialhaskell/stack/issues/3142)
+* `stack script`'s import parser will now properly parse files that
+  have Windows-style line endings (CRLF)
+
 
 ## 1.4.0
 
@@ -150,6 +197,8 @@ Other enhancements:
 * Upgraded `http-client-tls` version, which now offers support for the
   `socks5://` and `socks5h://` values in the `http_proxy` and `https_proxy`
   environment variables.
+* Binary "stack upgrade" will now warn if the installed executable is not
+  on the PATH or shadowed by another entry.
 
 Bug fixes:
 
@@ -1058,6 +1107,8 @@ Other enhancements:
 * `stack build --fast` turns off optimizations
 * Show progress while downloading package index
   [#1223](https://github.com/commercialhaskell/stack/issues/1223).
+* Allow running tests on tarball created by sdist and upload
+  [#717](https://github.com/commercialhaskell/stack/issues/717).
 
 Bug fixes:
 

diff --git a/doc/GUIDE.md b/doc/GUIDE.md
@@ -1425,7 +1425,7 @@ modified version of a dependency that hasn't yet been released upstream.
 
 Please note that when adding upstream packages directly to your project it is
 important to distinguish _local packages_ from the upstream _dependency
-packages_. Otherwise you may have trouble running `stack GHCi`. See
+packages_. Otherwise you may have trouble running `stack ghci`. See
 [stack.yaml documentation](yaml_configuration.md#packages) for more details.
 
 ## Flags and GHC options

diff --git a/doc/custom_snapshot.md b/doc/custom_snapshot.md
@@ -1,29 +1,59 @@
 # Custom Snapshots
 
-Custom snapshots allow you to create your own snapshots, which provide a list of
-specific hackage packages to use, along with flags and ghc-options.  The
-definition of a basic snapshot looks like the following:
+Custom snapshots were totally reworked with the extensible snapshots
+overhaul in Stack 1.6.0, see
+[the writeup](https://www.fpcomplete.com/blog/2017/07/stacks-new-extensible-snapshots)
+and
+[PR #3249](https://github.com/commercialhaskell/stack/pull/3249)). This
+documentation covers the new syntax only.
+
+Custom snapshots allow you to create your own snapshots, which provide
+a list of packages to use, along with flags, ghc-options, and a few
+other settings. Custom snapshots may extend any other snapshot that
+can be specified in a `resolver` field. The packages specified follow
+the syntax of `extra-deps` in the `stack.yaml` file, with one
+exception: to ensure reproducibility of snapshots, local directories
+are not allowed for custom snapshots (as they are expected to change
+regularly).
 
 ```yaml
-resolver: ghc-8.0
+resolver: lts-8.21 # Inherits GHC version and package set
+compiler: ghc-8.0.1 # Overwrites GHC version in the resolver, optional
 
+name: my-snapshot # User-friendly name
+
+# Additional packages, follows extra-deps syntax
 packages:
-  - unordered-containers-0.2.7.1
-  - hashable-1.2.4.0
-  - text-1.2.2.1
+- unordered-containers-0.2.7.1
+- hashable-1.2.4.0
+- text-1.2.2.1
 
+# Override flags, can also override flags in the parent snapshot
 flags:
   unordered-containers:
     debug: true
+
+# Packages from the parent snapshot to ignore
+drop-packages:
+- wai-extra
+
+# Packages which should be hidden (affects script command's import
+# parser
+hidden:
+  wai: true
+  warp: false
+
+# Set GHC options for specific packages
+ghc-options:
+  warp:
+  - -O2
 ```
 
 If you put this in a `snapshot.yaml` file in the same directory as your project,
 you can now use the custom snapshot like this:
 
 ```yaml
-resolver:
-  name: simple-snapshot  # Human readable name for the snapshot
-  location: simple-snapshot.yaml
+resolver: snapshot.yaml
 ```
 
 This is an example of a custom snapshot stored in the filesystem. They are
@@ -38,24 +68,6 @@ For efficiency, URLs are treated differently. If I uploaded the snapshot to
 `https://domain.org/snapshot-1.yaml`, it is expected to be immutable. If you
 change that file, then you lose any reproducibility guarantees.
 
-## Extending snapshots
-
-The example custom snapshot above uses a compiler resolver, and so has few
-packages.  We can also extend existing snapshots, by using the usual
-[resolver setting found in stack configurations](yaml_configuration.md#resolver).
-All possible resolver choices are valid, so this means that custom snapshots can
-even extend other custom snapshots.
-
-Lets say that we want to use `lts-7.1`, but use a different version of `text`
-than the one it comes with, `1.2.2.1`.  To downgrade it to `1.2.2.0`, we need a
-custom snapshot file with the following:
-
-```yaml
-resolver: lts-7.1
-packages:
-  - text-1.2.2.0
-```
-
 ### Overriding the compiler
 
 The following snapshot specification will be identical to `lts-7.1`, but instead
@@ -117,57 +129,3 @@ ghc-options:
   text:
     developer: true
 ```
-
-## YAML format
-
-In summary, the YAML format of custom snapshots has the following fields which
-are directly related to the same fields in the
-[build configuration format](yaml_configuration.md):
-
-* `resolver`, which specifies which snapshot to extend. It takes the same values
-  as the [`resolver` field in stack.yaml](yaml_configuration.md#resolver).
-
-* `compiler`, which specifies or overrides the selection of compiler. If
-  `resolver` is absent, then a specification of `compiler` is required. Its
-  semantics are the same as the
-  [`compiler` field in stack.yaml](yaml_configuration.md#compiler).
-
-Some fields look similar, but behave differently:
-
-* `flags` specifies which cabal flags to use with each package. In order to
-  specify a flag for a package, it *must* be listed in the `packages` list.
-
-* `ghc-options`, which specifies which cabal flags to use with each package. In
-  order to specify ghc-options for a package, it *must* be listed in the
-  `packages` list. The `*` member of the map specifies flags that apply to every
-  package in the `packages` list.
-
-There are two fields which work differently than in the build configuration
-format:
-
-* `packages`, which specifies a list of hackage package versions.  Note that
-  when a package version is overridden, no `flags` or `ghc-options` are taken
-  from the snapshot that is being extended.  If you want the same options as the
-  snapshot being extended, they must be re-specified.
-
-* `drop-packages`, which specifies a list of packages to drop from the snapshot
-  being overridden.
-
-## Future enhancements
-
-We plan to enhance extensible snapshots in several ways in the future. See
-[issue #1265, about "implicit snapshots"](https://github.com/commercialhaskell/stack/issues/1265).
-In summary, in the future:
-
-1) It will be possible to use a specific git repository + commit hash in the
-`packages` list, like in regular stack.yaml configuration. Currently, custom
-snapshots only work with packages on hackage.
-
-2) `stack.yaml` configurations will implicitly create a snapshot. This means
-that the non-local packages will get shared between your projects, so there is
-less redundant compilation!
-
-3) `flags` and `ghc-options` for packages which are not listed in `packages` are
-silently ignored. See
-[#2654](https://github.com/commercialhaskell/stack/issues/2654) for the current
-status of this.
diff --git a/doc/install_and_upgrade.md b/doc/install_and_upgrade.md
@@ -63,15 +63,9 @@ such.
 ## macOS
 
 We generally test on the current version of macOS, but Stack is known to work
-on El Capitan, Yosemite and Mavericks as well, and may also work on older
+on Sierra, El Capitan, Yosemite and Mavericks as well, and may also work on older
 versions (YMMV).
 
-**macOS Sierra warning**: There are new limitations in the dynamic linker that
-are causing problems for GHC versions earlier than 8.0.2 when building projects with many
-dependencies. GHC 8.0.2 is first used in LTS 8.0. See
-[#2577](https://github.com/commercialhaskell/stack/issues/2577) for more
-information.
-
 ### Installer script
 
 Run:
@@ -88,10 +82,7 @@ Run:
 
 ### Using Homebrew
 
-**macOS Sierra warning**: Homebrew's haskell-stack formula may not currently
-work on Sierra, so we suggest using the manual method above for now.
-
-If you have a popular [brew](http://brew.sh/) tool installed, you can just do:
+If you have the popular [brew](https://brew.sh/) tool installed, you can just do:
 
     brew install haskell-stack
 
@@ -100,7 +91,7 @@ but tend to be updated within a day or two.
 * Normally, Homebrew will install from a pre-built binary (aka "pour from a
 bottle"), but if `brew` starts trying to build everything from source (which
 will take hours), see
-[their FAQ on the topic](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/FAQ.md#why-do-you-compile-everything).
+[their FAQ on the topic](https://github.com/Homebrew/brew/blob/master/docs/FAQ.md#why-do-you-compile-everything).
 
 ### Notes
 
@@ -113,6 +104,9 @@ problems, see the linked FAQ entries:
 
   * [GHC 7.8.4 fails with `/usr/bin/ar: permission denied`](faq.md#usr-bin-ar-permission-denied)
   * [DYLD_LIBRARY_PATH is ignored](faq.md#dyld-library-path-ignored)
+
+
+If you are on OS X 10.12 ("Sierra") and encounter [GHC panic while building, see this issue](https://github.com/commercialhaskell/stack/issues/2577)
 
 ## Ubuntu