Repository navigation
README doesn't explain what gren does #78
Description
Installed gren, created github key, ran gren, no errors... but nothing seems to have happened?
gren --help yields nothing useful.
What exactly is the expected result of all this? README seems to miss the mark in terms of explaining what this (hopefully useful) tool does, I'm afraid.
FWIW, my console output:
kieffer@MacBook-Pro-3$ pwd
/Users/kieffer/projects/node-mime
kieffer@MacBook-Pro-3$ lsf
total 80
-rw-r--r-- 1 kieffer staff 1098 May 11 21:53 LICENSE
-rw-r--r-- 1 kieffer staff 1894 Sep 12 15:32 Mime.js
-rw-r--r-- 1 kieffer staff 5053 Sep 12 15:40 README.md
-rw-r--r-- 1 kieffer staff 150 Sep 12 15:32 cli.js
-rw-r--r-- 1 kieffer staff 114 Sep 12 15:32 index.js
-rw-r--r-- 1 kieffer staff 88 Sep 12 15:32 lite.js
drwxr-xr-x 35 kieffer staff 1190 Sep 12 15:44 node_modules/
-rw-r--r-- 1 kieffer staff 8168 Sep 12 15:44 package-lock.json
-rw-r--r-- 1 kieffer staff 962 Sep 12 15:44 package.json
drwxr-xr-x 6 kieffer staff 204 Sep 12 15:40 src/
drwxr-xr-x 4 kieffer staff 136 Sep 12 15:32 types/
kieffer@MacBook-Pro-3$ gren
Release task:
===================================
Getting the list of releases: ..... (0.49 secs)
1 releases found
Getting tags: .... (0.33 secs)
Tags found: v1.4.0, v1.3.6
Getting the tag dates ranges: .... (0.34 secs)
Creating the body blocks from releases:
Getting all closed issues: ...... (0.52 secs)
13 issues found
Skipping v1.4.0 (use --override to replace it)
kieffer@MacBook-Pro-3$ lsf
total 80
-rw-r--r-- 1 kieffer staff 1098 May 11 21:53 LICENSE
-rw-r--r-- 1 kieffer staff 1894 Sep 12 15:32 Mime.js
-rw-r--r-- 1 kieffer staff 5053 Sep 12 15:40 README.md
-rw-r--r-- 1 kieffer staff 150 Sep 12 15:32 cli.js
-rw-r--r-- 1 kieffer staff 114 Sep 12 15:32 index.js
-rw-r--r-- 1 kieffer staff 88 Sep 12 15:32 lite.js
drwxr-xr-x 35 kieffer staff 1190 Sep 12 15:44 node_modules/
-rw-r--r-- 1 kieffer staff 8168 Sep 12 15:44 package-lock.json
-rw-r--r-- 1 kieffer staff 962 Sep 12 15:44 package.json
drwxr-xr-x 6 kieffer staff 204 Sep 12 15:40 src/
drwxr-xr-x 4 kieffer staff 136 Sep 12 15:32 types/
kieffer@MacBook-Pro-3$
Activity
broofa commentedon Sep 12, 2017
Found https://github-tools.github.io/github-release-notes/examples after a bit of hunting around.
The way the
actionparam is documented could be clearer. IMHO, the first thing in the readme should be aUsagesection withgren [--action=[release|changelog] ...style notation. Then document each param, what it does, and provide an example below that. (My $.02)The animated gifs aren't very helpful. Would prefer simple copy/paste of console log for examples. Easier to follow.
[Edit: Part of the problem with the gifs is that you only see the last few lines of output - the most interesting part, generally - for a split second before it starts over. Frustrating.]
Other than that, thanks for a cool tool!
broofa commentedon Sep 12, 2017
Oh... and look, apparently
grendocumented the release under my project's "releases" tab. That's really cool... yet not at all obvious that's what's happening. (And, yes, maybe I should have surmised this was what was going to happen based on the name, but I was expecting it to generate a RELEASE_NOTES.md file or something like that.)dddom commentedon Sep 13, 2017
I suppose it's worth mentioning I think it’d be great if the first thing you read was about the philosophy of this tool, that it’s GITHUB RELEASE NOTES, how you should use GitHub to create the right content for this tool to use, what would be the steps or workflow, philosophy I’d need to adapt to be able to use this tool effectively, what benefits would that bring etc.
@broofa has a point about the gifs, I don’t find them useful either, because it’s not useful to see the process of printing the log and have it disappear immediately. Console output would be better in this case, if not even just concise screenshots (syntax highlighting is useful).
alexcanessa commentedon Sep 14, 2017
@broofa, @dddom good points.
I always had the impression that either the
README.mdor the documentation, in general, were clear enough.Thanks for your feedback, definitely going to address it.
broofa commentedon Sep 14, 2017
If I had a nickel for every time I thought my docs were obvious, only to be proven horribly wrong... :-)
Thanks for your patience with this noob.
alexcanessa commentedon Oct 8, 2017
@broofa the new README.md and documentation should fix this issue.
Closed by #85