Clarify purpose of `~/.stack/global/stack.yaml`

[borsboom]

The ~/.stack/global/stack.yaml file seems to be a common source of confusion (see #964, and I've seen the same thing a few other times). The stack.yaml documentation is pretty clear about its use, but I suspect in many cases people are just seeing a stack.yaml that exists under their ~/.stack and assuming it sets global default options without ever looking at that part of the documentation.

I'm thinking we should have stack put a comment at the top of ~/.stack/global/stack.yaml when it is generated stating what its use is and pointing people to the right place to put global defaults.

[drwebb]

In addition to comments for both files, I think we could enforce better naming to these files. change ~/.stack/stack.yaml to something like ~/.stack/default_options.yaml (someone could suggest a better name) and ~/.stack/global/stack.yaml to ~/.stack/global/global_stack.yaml. Basically there are to many stack.yaml named files floating around! Also we could pre-populate these files with whatever is hard coded making it even more obvious.

[k-bx]

+1 to renaming to something like ~/.stack/defaults.yaml

[rvion]

+1 to renaming defaults

[borsboom]

Here's what I'm thinking:

• Change the name of ~/.stack/stack.yaml to ~/.stack/config.yaml. "config" is consistent with many common tools, including cabal-install, ssh, and git, so I think its meaning will be clear.
• If ~/.stack/config.yaml doesn't exist, create an empty one containing a comment describing its purpose and pointing to the documentation URL
  • But: if ~/.stack/stack.yaml exists, auto-rename it to ~/.stack/config.yaml (and print a message to that effect) instead

Also, probably:

• Change the name of ~/.stack/global to ~/.stack/default-project
• Put a comment at the top of the automatically-generated ~/.stack/default-project/stack.yaml indicating that it will only be used when not in a real project. Also put a README in the directory to that effect.
• I don't think it's safe to rename the old directory automatically, since that would break any packages within. We could copy the stack.yaml from it to the new location, but we can't rename the directory So I'm thinking the existing ~/.stack/global should just be ignored, but a warning printed if it's present.

And maybe?

• Change the name of /etc/stack/config to /etc/stack/config.yaml, for consistency
• If /etc/stack/config exists, exit with error message to get the admin to rename it (I don't think it's heavily used, so this should not effect very many people)

I don't like that changing ~/.stack/global and /etc/stack/config could break people's existing setup, but I guess there's no time like the present...

[borsboom]

Ok, upon further reflection, thinking stack shouldn't attempt to rename/copy any files, and should just support using the old locations with deprecation warnings.

Additionally, maybe ~/.stack/global-project is better than ~/.stack/default-project.

And, finally, an idea: what if project config files (stack.yaml) only have project-specific options at the top level, and put non-project-specific options one level down under a non-project (or something) key (instead of combining project-specific and non-project specific options at the top level)? That would reduce confusion about which options are which kind? Or would it lead to extra confusion when people try to put non-project-specific options at the top level and wonder why it doesn't work?

[borsboom]

PR pushed: #1058