New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
borsboom opened this Issue Sep 10, 2015 · 6 comments

Comments

Projects
None yet
5 participants
@borsboom
Contributor

borsboom commented Sep 10, 2015

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

This comment has been minimized.

Contributor

drwebb commented Sep 10, 2015

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

This comment has been minimized.

Contributor

k-bx commented Sep 10, 2015

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

@rvion

This comment has been minimized.

Contributor

rvion commented Sep 11, 2015

+1 to renaming defaults

@borsboom borsboom changed the title from Add comment at top of `~/.stack/global/stack.yaml` to Clarify purpose of `~/.stack/global/stack.yaml` Sep 11, 2015

@borsboom borsboom added this to the P1: Must milestone Sep 12, 2015

@borsboom borsboom self-assigned this Sep 25, 2015

@borsboom

This comment has been minimized.

Contributor

borsboom commented Sep 26, 2015

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

This comment has been minimized.

Contributor

borsboom commented Sep 26, 2015

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 added a commit that referenced this issue Sep 26, 2015

Rename config files and clarify their purposes (#969)
* Rename `~/.stack/stack.yaml` to `~/.stack/config.yaml`
* Rename `~/.stack/global` to `~/.stack/global-project`
* Rename `/etc/stack/config` to `/etc/stack/config.yaml`
* Support old locations of the renamed paths, with deprecation warnings
* Clarify wording of some messages
* Write comment to top of new `~/.stack/config.yaml` describing its purpose
* Write comment to top of new `~/.stack/global-project/stack.yaml` describing its purpose
* Write `~/.stack/global-project/README` describing the purpose of the directory
@borsboom

This comment has been minimized.

Contributor

borsboom commented Sep 26, 2015

PR pushed: #1058

borsboom added a commit that referenced this issue Sep 27, 2015

Merge pull request #1058 from commercialhaskell/pr/969-rename-configs
Rename config files and clarify their purposes (#969)

@borsboom borsboom closed this Sep 27, 2015

@snoyberg snoyberg removed the ready label Sep 27, 2015

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment