Broken doc instructions for local extra-deps

[bitemyapp]

https://github.com/commercialhaskell/stack/blob/master/doc/yaml_configuration.md#local-file-path might not be correct or functional in current stable Stack.

Most experienced Stack users I know do something like this:

packages:
- thor/
- odin/
- friendlyId/
- horus/
- location:
    git: https://github.com/yesodweb/yesod
    commit: 1920604d672dca457e530be8498ee31b5a1f85b8
  subdirs:
    - yesod-core
    - yesod-test
  extra-dep: true
- location:
    git: https://github.com/dmjio/stripe
    commit: 35d1bea6e31e0540aaba78a6697a0e12cfb659b2
  extra-dep: true
  subdirs:
    - stripe-core
    - stripe-haskell
    - stripe-http-streams

Documentation at time of writing instead says:

Local file path

Like packages, local file paths can be used in extra-deps, and will be relative to the directory containing the stack.yaml file.

extra-deps:
- vendor/somelib

Note that if a local directory can be parsed as a package identifier, Stack will treat it as a package identifier. In other words, if you have a local directory named foo-1.2.3, instead of:

extra-deps:
- foo-1.2.3
You should use the following to be explicit:

extra-deps:
- ./foo-1.2.3

Nota bene: this is based on a user report, I haven't confirmed this is broken yet. Even if it isn't, an explanation of why the docs tell people to do the above instead of packages would be helpful. I think the relationship between packages and extra-deps has gotten a bit strained over time and I remember some people floating the suggestion that the overlap be reconciled.

[mgsloan]

Yeah, the docs for stable stack are at https://github.com/commercialhaskell/stack/blob/stable/doc/yaml_configuration.md / https://docs.haskellstack.org/en/stable/yaml_configuration . The docs on master are for the unreleased version of stack.

I am a little concerned that changes to stack.yaml format will break unintuitively for folks on older versions.
It may make sense to implement #1681 ("Check for recent version during calls?"), so that when more changes like this come in the future. Particularly, doing this check when a stack.yaml fails to parse could be good.

It may make sense to demand require-stack-version in order to use the new extra-deps syntax.

[snoyberg]

Docs are updated correctly, closing