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
@@ -17,207 +17,43 @@ Install `github-release-notes` via npm:
17
17
npm install github-release-notes -g
18
18
```
19
19
20
-
## Usage
20
+
## Setup
21
21
22
-
**gren** can be ran through the terminal, but before you can use it, you need to set up a couple of things.
23
-
24
-
### Github Informations
25
-
26
-
**gren** by default looks for your local git configuration to get the repo informations. This means you can run the command directly from the git repo folder.
27
-
28
-
Otherwise, you can run it from wherever and specify a different repo as target, with:
29
-
30
-
```shell
31
-
gren --username=[username] --repo=[repo name]
32
-
```
33
-
34
-
#### Token
35
-
36
-
To work, **gren** needs a `github token` (that can be easily generated following [this link](https://help.github.com/articles/creating-an-access-token-for-command-line-use/)). _You only need "repo" scope._
37
-
38
-
Once generated, you can run the gren command with the token as variable:
39
-
40
-
```shell
41
-
gren --token=your_token_here
42
-
```
43
-
44
-
Or you can add it to your `~/.bash_profile` or `~/.zshrc`) as follows:
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`):
45
24
46
25
```shell
47
26
export GREN_GITHUB_TOKEN=your_token_here
48
27
```
49
28
50
-
And you're ready to use it! Just run this command in your terminal:
29
+
## Basic Usage
51
30
52
31
```shell
32
+
# Navigate to your project directory
33
+
cd~/Path/to/repo
34
+
# Run the task
53
35
gren
54
36
```
55
37
56
-
The module will look for the last tag, get all the issues closed in the time between that tag and the one before, and it will build release notes and draft the new release!
57
-
58
-
## Options
59
-
60
-
Following the options for the module:
61
-
62
-
### Global options
63
-
64
-
| Command | Options | Description | Default |
65
-
| ------- | ------- | ----------- | ------- |
66
-
|`--username`|**Required**| The username of the repo _e.g. `github-tools`_|`null`|
67
-
|`--repo`|**Required**| The repository name _e.g. `github-release-notes`_|`null`|
68
-
|`--action`|`release``changelog`| The **gren** action to run. _(see details below for changelog generator)_|`release`|
69
-
|`--ignore-labels`|`wont_fix``wont_fix,duplicate`| Ignore issues that contains one of the specified labels. |`false`|
70
-
|`--ignore-issues-with`|`wont_fix``wont_fix,duplicate`| Ignore issues that contains one of the specified labels. |`false`|
71
-
|`--data-source`|`issues``commits`| The informations you want to use to build release notes. |`issues`|
72
-
|`--prefix`|**String**`e.g. v1.0.1`| Add a prefix to the tag version. |`null`|
73
-
|`--override`|**Flag**| Override the release notes if existing. |`false`|
74
-
|`--include-messages`|`merge``commits``all`| Filter the messages added to the release notes. _Only used when `data-source` used is `commits`|`commits`|
75
-
76
-
### Release options
77
-
78
-
| Command | Options | Description | Default |
79
-
| ------- | ------- | ----------- | ------- |
80
-
|`--draft`|**Flag**| Set the release as a draft. |`false`|
81
-
|`--prerelease`|**Flag**| To set the release as a prerelease. |`false`|
82
-
|`--tags`|`0.1.0``0.2.0,0.1.0``all`| A specific tag or the range of tags to build the release notes from. You can also specify `all` to write all releases. _(To override existing releases use the --override flag)_|`false`|
83
-
84
-
### Changelog options
85
-
86
-
| Command | Options | Description | Default |
87
-
| ------- | ------- | ----------- | ------- |
88
-
|`--time-wrap`|`latest``history`| The release notes you want to include in the changelog. |`latest`|
89
-
|`--changelog-filename`|**String**, like `changelog.md`| The name of the changelog file. |`CHANGELOG.md`|
90
-
91
-
92
-
### Config file
93
-
94
-
You can create a configuration file where the task will be ran, where to specify your options.
95
-
The options in the file would be camelCase *e.g*:
96
-
97
-
```json
98
-
{
99
-
"action": "release",
100
-
"timeWrap": "history",
101
-
"dataSource": "commits",
102
-
"ignoreIssuesWith": [
103
-
"wontfix",
104
-
"duplicate"
105
-
]
106
-
}
107
-
```
108
-
109
-
The accepted file extensions are the following:
110
-
111
-
-`.grenrc`
112
-
-`.grenrc.json`
113
-
-`.grenrc.yml`
114
-
-`.grenrc.yaml`
115
-
-`.grenrc.js`
116
-
117
-
#### Templates
118
-
119
-
You can configure the output of **gren** using templates. Set your own configuration inside the config file, which will be merged with the defaults, shown below:
120
-
121
-
```json
122
-
{
123
-
"template": {
124
-
"commit": "- {{message}}",
125
-
"issue": "- {{labels}} {{name}} {{link}}",
126
-
"issueInfo": {
127
-
"labels": "{{labels}}",
128
-
"label": "[**{{label}}**]",
129
-
"name": "{{name}}",
130
-
"link": "[{{text}}]({{url}})"
131
-
},
132
-
"release": "## {{release}} {{date}}",
133
-
"releaseInfo": {
134
-
"release": "{{release}}",
135
-
"date": "({{date}})"
136
-
}
137
-
}
138
-
}
139
-
```
140
-
141
-
## Examples
38
+
Otherwise, you can run it anywhere passing the repo information:
142
39
143
-
The ways to use **gren** are various.
144
-
145
-
### Simple
146
-
147
-
The simple way, just looks for the last tag, gets all the issues closed between that tag and the one before and creates the new release with the generated body.
148
-
149
-
```
150
-
gren
151
-
```
152
-
153
-
### Commit messages
154
-
155
-
Adding the flag `--data-source=commits` will change the source of the release notes to be the commit messages.
156
-
157
-
```
158
-
gren --data-source=commits
159
-
```
160
-
161
-
### Release specific tags
162
-
163
-
The flag `--tags` accepts one or two tags.
164
-
If you only give one tag, it will get the issues (or commit messages) between that tag and the one before.
165
-
If you give two tags it will generate the release notes with the issues (or commit messages) between those two tag dates.
166
-
167
-
```
168
-
gren --tags=2.0.0,1.0.0
169
-
```
170
-
171
-
### Override an existing release
172
-
173
-
If you trying to create an existing release, **gren** will throw an error *"0.3.0 is a release, use --override flag to override an existing release!*
174
-
If you want then to override, simple use:
175
-
176
-
```
177
-
gren --override --tags=0.3.0
178
-
```
179
-
180
-
### Write all existing tags
181
-
182
-
You can run the task to generate release notes for all existing tags.
183
-
Releases that already exist will be skipped. To override them, use the flag `--override`
184
-
185
-
```
186
-
gren --override --tags=all
40
+
```shell
41
+
gren --username=[username] --repo=[repo name]
187
42
```
188
43
189
-
## Changelog Generator
190
-
191
-
**gren** can also update generate the changelog.
192
-
193
-
The following command, will get the latest release notes, and add it to an existing file or create it in the same directory where you run the command.
44
+
To use a specific token you can specify it as option:
194
45
195
46
```shell
196
-
gren --action=changelog
47
+
gren --token=[your token]
197
48
```
198
49
199
-
The generated release notes will be added at the top of the file, and will look like this:
200
-
201
-
> # Changelog
202
-
## v0.4.3 (02/03/2016)
203
-
[**bug**] This is a issue name [#123](https://github.com/github-tools/github-tools)
204
-
205
-
### Generate a full changelog
206
-
207
-
If tou want to generate the whole changelog, you need to use the `--time-wrap=history`. This will generate the changelog based on all release notes.
208
-
209
-
If you want to override the existing changelog, use `--override`. This will also generate the release notes from scratch.
**Gren** has two main usages: `release` and `changelog`.
57
+
You can select the action with the `--action` option.
222
58
223
-
Find the full documentation for JavaScript function here: [http://github-tools.github.io/github-release-notes/](http://github-tools.github.io/github-release-notes/)
59
+
[See few examples here](https://github-tools.github.io/github-release-notes/examples.html)
0 commit comments