Improve `stack upgrade --help` documentation

[psibi]

Right now, I have a feeling that it's too negative for these two options:

  --force-download         Download a stack executable, even if the version
                           number is older than what we have
  --binary-version ARG     Download a specific version, even if it's out of date

Can it be changed to something like this:

  --force-download         Download the latest available stack executable
  --binary-version ARG     Download a specific stack version

I can submit a PR if there is no opposition. :)

[mgsloan]

Hmm, not sure if that updated doc for --force-download is correct. Downloading the latest (even if it's older than current) seems like the main use for it, but it could be combined with --binary-version, and you wouldn't get the latest.

Changing the --binary-version doc seems fine, I'd take a PR for that.

[psibi]

@mgsloan I don't think that's quite correct (or I'm understanding something wrong). The flag --binary-version can be used independently to download an executable of a specific version:

sibi::casey { ~ }-> stack upgrade --binary-version 1.4.0
Current Stack version: 1.4.0, available download version: 1.4.0
Forcing binary upgrade
Querying for archive location for platform: linux-x86_64-static
Downloading from: https://github.com/commercialhaskell/stack/releases/download/v1.4.0/stack-1.4.0-linux-x86_64-static.tar.gz
Download complete, testing executable
Version 1.4.0, Git revision e714f1dd3fade19496d91bd6a017e435a96a6bcd (4640 commits) x86_64 hpack-0.17.0
New stack executable available at /home/sibi/.local/bin/stack

You can see that it uses force binary upgrade even when the --force-download option isn't given. I think the whole confusion arises from the name of the flag. Probably instead of --force-download, it should have been named as --download-executable. But probably it's too late to change that.

[mgsloan]

It is certainly true that --binary-version implies --force-download. It's a weird case, but the user could specify --force-download even though it doesn't make a difference. In that case, it wouldn't download the latest.

[psibi]

It's a weird case, but the user could specify --force-download even though it doesn't make a difference.

That's why I wanted to change the help string for --force-download as I have proposed above. I believe most people would just want to upgrade to the latest stack executable version. And I feel making that clear would be better. Right now the way it's documented, I feel the only way of upgrading to latest version is by doing this:

stack upgrade --force-download --binary-version 1.4.0

Infact, I discovered this feature from Michael Snoyman's tweet. Then, when I went to see the help string on what it does, I was confused.

[mgsloan]

Fair 'nough, seems reasonable!

[seanwestfall]

Since this issue is related, I don't think it's necessary to open another issue for it, but is there anyway to get stack to upgrade to the global stack executable? Right now when you run stack upgrade it creates the executable at /home/*/.local/bin/stack when the upgrade completes this is the message shown: New stack executable available at /home/***/.local/bin/stack is there any way to have it add the executable to the global system bin?

[mgsloan]

@seawestfall No flag for that currently. Also different distributions may have different opinions on /usr/local/bin vs /usr/bin/ etc. A straightforward workaround is to copy / move from ~/.local/bin/stack to your global bin.

[kadoban]

Was there agreement on how or if the --force-download message should change? I was going to do a quick PR, but I couldn't tell.

[psibi]

@kadoban Go for it. Michael agreed with my proposal (I hope), so you can just replace it with the messages I have proposed initially.

[alexeyzab]

Hey everyone! I figured I'd go ahead and add this.