You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Add all the defaults to Release.js
* First change for README.md file
* Create Gren task and add functionality for the changelog command
* Update node version in travis
* Change the task for the Gren
* Update options description
* Use native Object.assign for the program options to avoid deep merging
* Prettify the utils task logger
* Accept * as all tags
* Get github env informations from Program.js
* Update the generated documentation
* Change the name in the docs
* Update documentation
* Add code coverage with mocha/istanbul
* Update organisation name in the package.json
* Get the token from process.env rather than command
* Update documentation
* Create tests
* Add npm downloads badge
[](https://gitter.im/github-release-notes/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
> Node module that generates release notes based on commit messages or closed issues between tags. It also can create a full changelog or add the latest release notes to the existing changelog file.
10
+
## Motivation
9
11
10
-
If you want to include it in a task, you can use [grunt-github-release-notes](https://github.com/github-tools/grunt-github-release-notes)
Everyone would also rather avoid maintaining them. What a hassle to have to evaluate what issues have been solved between two points in project's timeline, what types of problems they were, are they important to inform the users about, what issues solved them etc.
15
+
16
+
Wouldn't it be great to get fantastic release notes compiled for you automaticaly based on all the hard work you put into your GitHub issues and pull requests.
17
+
18
+
## OK, what can `gren` do for me?
19
+
20
+
`gren` is a small helpful robot that will do for you just that! To put simply, it can create a release from a tag and compile the release notes using issues or commits.
21
+
22
+
It also can generate a `CHANGELOG.md` file based on the release notes (or generate a brand new).
The main motivation for bringing `gren` to life was the need for auto generating release notes for every tag in a project.
34
+
The process, [as explained here](https://help.github.com/articles/creating-releases/), requires to go to your project's releases page in GitHub, draft that tag as a new release and manually add what I remembered has changed.
35
+
36
+
Let `gren` take care of that for you. It automates this process and also writes release notes for you, creating something like this:
> -[#26](https://github.com/github-tools/github-release-notes/issues/26) Use external config file
44
+
> -[#23](https://github.com/github-tools/github-release-notes/issues/23) Introduce templates for the issues
45
+
> -[#19](https://github.com/github-tools/github-release-notes/issues/19) Add an "ignore label" flag
46
+
> -[#12](https://github.com/github-tools/github-release-notes/issues/12) Add the chance to rebuild the history of release notes
47
+
>
48
+
> #### Bug Fixes:
49
+
>
50
+
> -[#29](https://github.com/github-tools/github-release-notes/issues/29) Remove escaping character on regex
51
+
> -[#24](https://github.com/github-tools/github-release-notes/issues/24) The changelog action doesn't compile latest release
52
+
53
+
_(yes, this is one of_ 🤖 _'s actual releases)_
54
+
55
+
## Feed `gren` 🤖
56
+
57
+
Where is the data coming from? There are two options:
58
+
59
+
### `issues` (⭐)
60
+
61
+
If you manage your project with issues, that's where all the information about a change are.
62
+
Issue labels increase the level of depth of what the release notes should show, helping `gren` to group the notes.
63
+
64
+
_e.g. if you see the example above, the issues are grouped by the two labels `enhancement` and `bug`, then customised via a config file._
65
+
66
+
`gren` generates those notes by collecting all the issues closed between a tag (defaults to latest) and the tag before it (or a tag that you specify).
67
+
If you want to be more accurate on the issues that belong to a release, you can group them in [milestones](https://github-tools.github.io/github-release-notes/examples.html#milestones) and use only the issues that belong to that Milestone.
68
+
69
+
> The output above is a result of release notes built from issues.
70
+
71
+
#### Help 🤖 to write wondeful stuff (issues)
72
+
73
+
In order to have spliendid generated release notes, we reccomend to follow these convensions:
74
+
75
+
1. Start the title with a verb (e.g. Change header styles)
76
+
2. Use the imperative mood in the title (e.g. Fix, not Fixed or Fixes header styles)
77
+
3. Use labels wisely and assign one label per issue. `gren` has the [option to ignore issues](#)_(alex: put link to options)_ that have a specified issues.
78
+
79
+
### `commits`
80
+
81
+
The simplest way of getting data is from the commits you write.
82
+
Even though it doesn't require a machine-readable commit, still would be better to have them in a nice format.
83
+
84
+
The output would then use commit messages (title + description) to look something like:
85
+
86
+
> ## v0.9.0 (17/05/2017)
87
+
>
88
+
> - Filter milestones (#75)
89
+
> * Create milestones data-source option
90
+
> * Add documentation for the milestones option
91
+
> - Support GitHub enterprise (#73)
92
+
> * Support GitHub enterprise
93
+
> * Add api-url to options documentation
94
+
> - Update CHANGELOG.md
95
+
96
+
#### Help 🤖 to write wondeful stuff (commits)
97
+
98
+
In order to have spliendid generated release notes, we reccomend to follow these convensions:
99
+
100
+
1. Start the subject line with a verb (e.g. Change header styles)
101
+
2. Use the imperative mood in the subject line (e.g. Fix, not Fixed or Fixes header styles)
102
+
3. Limit the subject line to about 50 characters
103
+
4. Do not end the subject line with a period
104
+
5. Separate subject from body with a blank line
105
+
6. Wrap the body at 72 characters
106
+
7. Use the body to explain _what_ and _why_ not _how_
11
107
12
108
## Installation
13
109
@@ -17,43 +113,90 @@ Install `github-release-notes` via npm:
17
113
npm install github-release-notes -g
18
114
```
19
115
20
-
## Setup
116
+
###Setup
21
117
22
-
First generate a `github token`at [this link](https://help.github.com/articles/creating-an-access-token-for-command-line-use/)._You only need "repo" scope._
23
-
Then add this to `~/.bash_profile` or `~/.zshrc`):
118
+
First, generate a `GitHub token`, _with **repo** scope_, at [this link](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/).
119
+
Then add this line to `~/.bash_profile`(or `~/.zshrc`):
24
120
25
121
```shell
26
122
export GREN_GITHUB_TOKEN=your_token_here
27
123
```
28
124
29
125
## Basic Usage
30
126
127
+
`gren` gets the repo information directly from the folder where `git` is initialised.
128
+
31
129
```shell
32
130
# Navigate to your project directory
33
131
cd~/Path/to/repo
34
-
# Run the task
35
-
gren
132
+
# Run the task (see below)
133
+
gren release
134
+
```
135
+
136
+
Otherwise, you can run it _anywhere_ passing the repo information:
Otherwise, you can run it anywhere passing the repo information:
142
+
If you don't want to save the token, you can specify one as an option:
39
143
40
144
```shell
41
-
gren --username=[username] --repo=[repo name]
145
+
gren release --token=[your token]
42
146
```
43
147
44
-
To use a specific token you can specify it as option:
148
+
### [See all the options here](https://github-tools.github.io/github-release-notes/options.html)
149
+
150
+
### Commands
151
+
152
+
There are two main commands that can be ran with 🤖:
153
+
154
+
#### `gren release`
155
+
156
+
`gren` will look for the latest tag, draft a new release using the issues closed between when that tag and the one before were created and publish that release in your **release** panel in your GitHub repo. ([@see how to feed 🤖](#feed-gren-)).
157
+
158
+
#### `gren changelog`
159
+
160
+
Create a `CHANGELOG.md` file using all the release notes of the repo _(like the ones generated by_ 🤖 _)._
161
+
If the file exists already, use the `--override` option to proceed.
45
162
46
163
```shell
47
-
gren --token=[your token]
164
+
gren changelog --override
48
165
```
49
166
50
-
### Demo
167
+
To generate a brand new release notes, using the same approach as per the releases, you have to run the command with the `--generate` option.
168
+
169
+
```shell
170
+
gren changelog --generate
171
+
```
172
+
173
+
### Help! 🆘
174
+
175
+
`gren` is using [Commander.js](https://github.com/tj/commander.js) which generates the `--help` section.
176
+
To trigger the help of a command, run:
177
+
178
+
```shell
179
+
# General usage
180
+
gren --help
181
+
# Command usage
182
+
gren help release # or gren release --help
183
+
```
184
+
185
+
It's also possible to see all the examples [here](https://github-tools.github.io/github-release-notes/examples.html) or directly in the terminal:
You can create a configuration file where the task will be ran, where to specify your options. [See how to set up the config file](https://github-tools.github.io/github-release-notes/options.html#configuration-file)
194
+
The accepted file extensions are the following:
55
195
56
-
**Gren** has two main usages: `release` and `changelog`.
57
-
You can select the action with the `--action` option.
196
+
-`.grenrc`
197
+
-`.grenrc.json`
198
+
-`.grenrc.yml`
199
+
-`.grenrc.yaml`
200
+
-`.grenrc.js`
58
201
59
-
[See full documentation here](https://github-tools.github.io/github-release-notes)
202
+
### [See full documentation here](https://github-tools.github.io/github-release-notes)
0 commit comments