Some observed usability issues
Closed this issue · 4 comments
I like the ideas behind this project, but I struggled to get it working with my existing setup. Do with these comments what you will, I just wanted to give some constructive feedback. Some problems I observed:
No errors are reported if a file wasn't found
There is just no output. I spent a while figuring out why there was no output from kontemplate template, even though everything looked fine. Turns out the path was incorrect.
The path to a "service folder" silently fails if it is a file instead of a directory
I assumed that kontemplate ... --include foo/bar/baz.yml would work, but it doesn't. It will try to silently load all files below the non-existent directory foo/bar/baz.yml, which obviously fails. I don't actually mind this being unspported, but it would be nice to get an error.
Paths are relative to the context yml files
I expected paths to be relative to the current working directory, but apparently they are relative to the yml files that contain the context definitions. If the context yml file are in a subdirectory you'll get commands like kontemplate template config/environments/staging.yml --include ../../apps/site-static. This reads super weird if apps/site-static actually exists in the current directory.
Package.json files are included by default
These are commonly used for Node projects and it would be nice if they were excluded by default, or if there were a way for me to manually exclude them.
Thanks for the comments, I'll take care of the silent "failures" asap.
The other points need a bit more thinking on my side, probably won't get to that before the weekend!
Okay, going through one-by-one:
No errors are reported if a file wasn't found
The path to a "service folder" silently fails if it is a file instead of a directory
Will be addressed by #81, but I won't be able to deal with that today
Paths are relative to the context yml files
This is intended, and should probably be documented better. A resource set has a name and a path field, the path defaults to the name if it isn't set explicitly, and this path is always relative to the file in which it is defined.
When using --include / --exclude you aren't dealing with "paths" but rather with the "names" of resource sets, I see how this can be confusing and will try to find a way to make it more obvious (there is some documentation work going on at the moment in, for example, #74 and the new website).
Package.json files are included by default
In my use-case, application source is not in the same folder as an application's resource sets. However I believe that #81 will let you address this by specifying a specific file containing the resources to be templated, stay tuned!
Thanks for your swift and thoughtful response! Overall I think that the improvements you suggest accurately address the problems that I experienced.
Regarding the file/folder issue – if I can specify a single file per resource that would help tremendously. I can also imagine an "exclude pattern" of some kind being useful.
This issue has been sitting for quite a while, sorry about that. As there are follow-up tasks I'll close this in favour of those and aim at getting a 1.3.0 with all current pending fixes out ASAP.