Skip to content

Commit 61b4d75

Browse files
RobertDeRoseRobertDeRose
authored
Merge pull request #40 from Dorthu/feature/gitchangelog
Feature/gitchangelog
2 parents a51b9bf + bee1eea commit 61b4d75

File tree

3 files changed

+239
-0
lines changed

3 files changed

+239
-0
lines changed

‎.gitchangelog.rc

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
## gitchangelog.rc
2+
## ---------------
3+
##
4+
## This file is a configuration for gitchangelog, found here:
5+
##
6+
## https://github.com/vaab/gitchangelog
7+
##
8+
## This is a tool for generating changelogs from the output of a git log
9+
## statement. This configuration file controls how the config file is
10+
## generated.
11+
##
12+
## Expected Commit Message Format
13+
## ------------------------------
14+
##
15+
## ===============================
16+
## [tag?] [commit message subject]
17+
##
18+
## <commit message body text?>
19+
## * [changelog information]
20+
## <commit message body text>
21+
## ===============================
22+
##
23+
## In the above example, [tag] is optional and one of:
24+
##
25+
## * brk: for breaking changes
26+
## * new: for new features
27+
## * bug: for bug fixes
28+
## * ref: for refactors
29+
##
30+
## The bracketed text in the tag is optional. Tags should be applied to indicate
31+
## that a commit should appear in the changelog, and should reflect which section
32+
## of the changelog the commit should appear under.
33+
##
34+
## If a tag is present, the [commit message subject] will appear as a bullet
35+
## point in the resulting changelog, in the section indicated by [tag]. This
36+
## should summarize the change.
37+
##
38+
## In many (maybe most) cases, more information is required to describe a change
39+
## than will fit in a commit subject. This should be included in the body of the
40+
## commit message, as indicated by [changelog information] above. These lines
41+
## must start with an astrisk followed by a single whitespace (* ) with any amount
42+
## of whitespace before the astrisk. All levels of indentation will be collapsed
43+
## into subbullets of the [commit message subject] bullet point.
44+
##
45+
## Example Commit Message
46+
## ----------------------
47+
##
48+
## ===================================================
49+
## new: adds a cool new feature
50+
##
51+
## ABC-123 #done
52+
##
53+
## * Adds GET /cool/feature endpoint
54+
## * Represents a collection of cool features
55+
## ===================================================
56+
##
57+
## Example Output
58+
## --------------
59+
##
60+
## Features:
61+
##
62+
## * Adds a cool new feature
63+
## * Adds GET /cool/feature
64+
## * Represents a collection of cool features
65+
##
66+
## Generating a Changelog
67+
## ----------------------
68+
##
69+
## To generate a changelog for all commits, simply run gitchangelog:
70+
##
71+
## gitchangelog
72+
##
73+
## To generate a changelog to a specific tag, run gitchangelog like so:
74+
##
75+
## gitchangelog ...<tag>
76+
##
77+
## To generate a changelog between two tags, run gitchangelog like so:
78+
##
79+
## gitchangelog <tag-1>...<tag-2>
80+
##
81+
## All of these will output the changelog to the terminal.
82+
##
83+
## About This File
84+
## ---------------
85+
##
86+
## This configuration file should live at the root of the project using it, and
87+
## despite its (required) filename, is a python script that is called by the
88+
## gitchangelog program to grab settings and functions used to generate the
89+
## changelog. This file depends on .gitchangelog.tpl, which must live alongside
90+
## it, and is expected to be a mustache template file controlling how the
91+
## changelog is outputted. This file _should_ be tracked by git.
92+
import re
93+
from itertools import filterfalse
94+
95+
## Section Regexps
96+
##
97+
## This defines what is looked for in the subject of a commit to decide where,
98+
## if anywhere, the commit is added to the changelog.
99+
##
100+
## This setup defines the follow groups:
101+
## * Breaking - subject starts with brk:
102+
## * Features - subject starts with new:
103+
## * Refactors - subject starts with ref:
104+
## * Bugfixes - subject starts with bug:
105+
section_regexps = [
106+
('Breaking', [
107+
r'^brk:',
108+
]),
109+
('Features', [
110+
r'^new:'
111+
]),
112+
('Refactors', [
113+
r'^ref:'
114+
]),
115+
('Bugfixes', [
116+
r'^bug:'
117+
]),
118+
]
119+
120+
## Body Processing
121+
##
122+
## Commit message bodies are mostly ignored, but if you want bullet points nested
123+
## under your commit message subject, include them like so:
124+
##
125+
## * This will appear under the title
126+
##
127+
## These should be used to add specific details about what you changed, if the
128+
## change was big enough that the single-line message can't convey it all
129+
## adequately. Don't be shy with these - details are important.
130+
@TextProc
131+
def only_bullets(s):
132+
"""
133+
Given the commit body, removes any lines that don't match vaguely this
134+
format:
135+
136+
* Does a thing
137+
138+
For example, if given a commit message like this:
139+
140+
new: Adds support for something
141+
142+
This is for https://jira.linode.com/browser/ARB-123
143+
144+
* Adds GET /some/thing
145+
* Adds GET /some/thing/:id
146+
147+
this will return:
148+
149+
* Adds GET /some/thing
150+
* Adds GET /some/thing/:id
151+
"""
152+
lines = s.split('\n')
153+
lines = filterfalse(
154+
lambda c: not re.search(r'^ *\* ', c),
155+
lines
156+
)
157+
lines = [l.split('*', 1)[1].strip() for l in lines if l]
158+
lines = '\n * '.join(lines)
159+
if lines:
160+
lines = ' * '+lines
161+
return lines
162+
163+
body_process = only_bullets
164+
165+
## Subject Processing
166+
##
167+
## Commit message subjects are left wholly intact, except that the grouping tag
168+
## is removed (since it is used as metadata) and the first word is capitalized.
169+
## A commit message subject like this:
170+
##
171+
## ref moved permissions logic into user object
172+
##
173+
## becomes this instead:
174+
##
175+
## Moved permissions logic into user object
176+
##
177+
## That message will appear in the "Refacotrs" group, preserving the original
178+
## intention of the tag.
179+
@TextProc
180+
def strip_flag(s):
181+
"""
182+
This function is used to strip the flag from the commit summary before adding
183+
it to the changelog. All commits summaries considered will have a tag if
184+
they matched the section regexes, so we will assume that the first word can
185+
be removed.
186+
"""
187+
return ' '.join(s.split(' ')[1:])
188+
189+
subject_process = strip_flag | ucfirst
190+
191+
output_engine = mustache(".gitchangelog.tpl")

‎.gitchangelog.tpl

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{{#versions}}
2+
{{#sections}}
3+
{{label}}:
4+
5+
{{#commits}}
6+
* {{subject}}
7+
{{#body}}
8+
{{body_indented}}
9+
{{/body}}
10+
{{/commits}}
11+
12+
{{/sections}}
13+
14+
{{/versions}}

‎README.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,40 @@ to run the prebuild script and start the development server. Connect to
2626
make will be applied on the fly, but you may occasionally find that you have to
2727
restart it.
2828

29+
### Making Commits
30+
31+
We use [gitchangelog](https://github.com/vaab/gitchangelog) to generate our
32+
changelogs for this repository. Please begin commit messages with one of these
33+
prefixes to have them included in the changelog:
34+
35+
| Tag | Meaning |
36+
| new | Features |
37+
| bug | Bug Fixes |
38+
| ref | Refactors |
39+
| brk | Breaking Changes |
40+
41+
If you have more information to include in the changelog, include them as bullet
42+
points below, starting the line with an asterisk.
43+
44+
Example:
45+
46+
```bash
47+
new: Added docs for /some/thing
48+
49+
This text is ignored
50+
51+
* More information in the changelog
52+
```
53+
54+
This will produce the following output:
55+
56+
```
57+
Features:
58+
59+
* Added docs for /some/thing
60+
* More information in the changelog
61+
```
62+
2963
## Scripts
3064

3165
The `prebuild.js` script converts yaml into a js file imported by the app.

0 commit comments

Comments
 (0)