Skip to content
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
Closed

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

borsboom opened this issue Sep 10, 2015 · 6 comments

Comments

@borsboom
Copy link
Contributor

@borsboom 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
Copy link
Contributor

@drwebb 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
Copy link
Contributor

@k-bx k-bx commented Sep 10, 2015

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

@rvion
Copy link
Contributor

@rvion rvion commented Sep 11, 2015

+1 to renaming defaults

@borsboom borsboom changed the title Add comment at top of `~/.stack/global/stack.yaml` 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
Copy link
Contributor Author

@borsboom 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
Copy link
Contributor Author

@borsboom 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 `~/.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
Copy link
Contributor Author

@borsboom borsboom commented Sep 26, 2015

PR pushed: #1058

borsboom added a commit that referenced this issue Sep 27, 2015
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
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants