Outdated documentation about adding a remote git repo in stack.yaml

[Lysxia]

(Version 1.9.1.1, Git revision a953002 (6170 commits) x86_64)

The manual gives two different ways of adding a dependency via git (that one can find in a search using the keyword git):

• https://docs.haskellstack.org/en/stable/nonstandard_project_init/#using-git-repositories
• https://docs.haskellstack.org/en/stable/yaml_configuration/#git-and-mercurial-repos

I couldn't get the first one to work (even though it's the first result). The second is fine.

Steps to reproduce

1. Take any stack project (or create one).
2. Add some package foo that can be found on a remote git repo as a dependency to the package
3. Use either of the above two methods to add foo to stack.yaml
4. stack build: the first method results in an error, the second doesn't.

So one of these seems outdated. It's odd that the error is not about invalid syntax, but stack simply seems to ignore that location: field under packages:.

[mihaimaruseac]

Checking whether this is a regression or just outdated documentation

[dbaynard]

It’s definitely a deprecation — see https://www.fpcomplete.com/blog/2017/07/stacks-new-extensible-snapshots#four-package-locations (implemented in #3249).

…packages still supports local file paths, Git repos, and HTTP(S) URLs, but for the latter two requires you to explicitly state extra-dep: as either true or false.

Then further down

• Everyone could transition from their current extra-dep: true syntax over the next few versions before we remove the old support
  I'm not normally in favor of breaking backwards compatibility in Stack, but miscategorized extra deps has resulted in much confusion, so I'd be happy to see it go, even if it requires rewriting stack.yaml files over time.

---

So

1. @Lysxia does it work with an explicit extra-dep statement?
2. @snoyberg it wasn't clear from a brief glance at the changelog when/whether the old syntax has been deprecated. It appears from this issue that is has — is that correct?

Whatever happens, we need to change the docs. Depending on 1 we either update to reflect the requirement for an explicit extra-dep or just indicate that this is old behaviour.

It would be good to ensure that stack recognises the old stack.yaml format — and possibly even correct the error. @Lysxia What error do you actually see?

[Lysxia]

Indeed it works with an extra-dep key. Without it here's a sample error:

Error: While constructing the build plan, the following exceptions were encountered:

Unknown package: generic-recursion-schemes

Some different approaches to resolving this:

  * Consider trying 'stack solver', which uses the cabal-install solver to attempt to find some working build configuration. This can be convenient when dealing with many complicated constraint
    errors, but results may be unpredictable.


Plan construction failed.

That is if the package is not on Hackage. If it is, you get either the usual error if it is not in your resolver, or stack installs whatever it finds in your resolver.

A big source of confusion for me was the fact that stack seems to just ignore that field (without the extra-dep key). I would expect at least a warning about it.

[dbaynard]

OK, so two things are needed to resolve the issue fully

1. Correct the docs to indicate that using packages without extra-dep is deprecated, that using packages for dependency is old behaviour, and recommending the correct formulation.
2. Parse the old syntax and error with how to resolve the issue.

@Lysxia Would you like to tackle one, or perhaps both (please no animal names for functions)?

[Lysxia]

Sadly I don't have time to work on this in the near future, although I would have liked to. But thanks for the offer. ;)

[snoyberg]

Sorry, I didn't notice this issue before. I wasn't even aware of the first doc. I'm going to send a PR to have it point to the YAML configuration doc instead.