-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathgreat_commit_messages.html
316 lines (280 loc) · 9.43 KB
/
great_commit_messages.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
<!DOCTYPE html><html><head><title>Great Commit Messages</title><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0" /><style type='text/css'>
body {
font-family: 'Helvetica';
letter-spacing:-5px;
background:#000;
background-size:100%;
background-repeat: no-repeat;
color:#fff;
margin:0;
padding:0;
font-weight:bold;
}
h1, h2, h3, p {
margin:0;
}
em, a {
font-style:normal;
color:#8dbd0c;
}
p {
display: none;
}
a {
background: #34d0e7;
color:#000;
text-decoration:none;
}
img {
width:100%;
height:100%;
}
div {
cursor:pointer;
cursor:hand;
position:absolute;
top:0px;
left:0px;
padding:75px;
line-height:97%;
}
div.center {
text-align:center;
}
div.imageText {
text-shadow:0px 0px 5px rgba(0,0,0,0.2);
}
span.footnoteRight {
position: absolute;
bottom: 0;
right: 0;
font-size: .3em;
text-align:right;
}
</style><script type='text/javascript'>
window.onload = function() {
var s = document.getElementsByTagName('div'), ti;
if (!s) return;
var big = { current: 0, forward: fwd, reverse: rev, go: go, length: s.length };
window.big = big;
function resize() {
var w = window.innerWidth, h = window.innerHeight, e = s[big.current];
e.style.fontSize = h + 'px';
for (var i = h - 2; e.offsetWidth > w || e.offsetHeight > h; i -= 2) {
e.style.fontSize = i + 'px';
}
e.style.marginTop = ((h - e.offsetHeight) / 2) + 'px';
}
function go(n) {
big.current = n;
var e = s[n], t = parseInt(e.dataset.timeToNext || 0, 10);
document.body.className = e.dataset.bodyclass || '';
for (var k = 0; k < s.length; k++) s[k].style.display = 'none';
e.style.display = 'inline';
if (e.firstChild && e.firstChild.nodeName === 'IMG') {
document.body.style.backgroundImage = 'url("' + e.firstChild.src + '")';
e.firstChild.style.display = 'none';
if ('classList' in e) e.classList.add('imageText');
} else {
document.body.style.backgroundImage = '';
document.body.style.backgroundColor = e.style.backgroundColor;
}
if (ti !== undefined) window.clearInterval(ti);
if (t > 0) ti = window.setTimeout(fwd, (t * 1000));
resize();
if (window.location.hash !== n) window.location.hash = n;
document.title = e.textContent || e.innerText;
}
document.onclick = function() { go(++big.current % (s.length)); };
function fwd() { go(Math.min(s.length - 1, ++big.current)); }
function rev() { go(Math.max(0, --big.current)); }
document.onkeydown = function(e) {
if (e.which === 39 || e.which === 34 || e.which === 40) fwd();
if (e.which === 37 || e.which === 33 || e.which === 38) rev();
};
document.ontouchstart = function(e) {
var x0 = e.changedTouches[0].pageX;
document.ontouchend = function(e2) {
var x1 = e2.changedTouches[0].pageX;
if (x1 - x0 < 0) fwd();
if (x1 - x0 > 0) rev();
};
};
function parse_hash() {
return Math.max(Math.min(s.length - 1,
parseInt(window.location.hash.substring(1), 10)), 0);
}
if (window.location.hash) big.current = parse_hash() || big.current;
window.onhashchange = function() {
var c = parse_hash();
if (c !== big.current) go(c);
};
window.onresize = resize;
go(big.current);
};
</script></head><body>
<div><em>Great</em> Commit Messages</div>
<p>
Today, I'd like to talk about Great Commit Messages:
+ Why they're important
+ The 7 Rules for Writing Them
</p>
<div>Why</div>
<p>
When it comes to writing great commit messages,
"Why" is both the question and the answer.
Let's start with the question:
</p>
<div>Why <em>version control</em>?</div>
<p>
Why do we use version control?
(What if we didn't?)
...
+ System of Record
+ Collaboration
+ Coordination
+ Authoritative Source on the Code
</p>
<div>Version control is <em>important</em></div>
<p>
I think we can all agree with this statement
Anybody who thinks life would be better without version control?
Since we all agree that Version Control is important,
what I'd like to convince you of today is that version control
can work even harder for you
</p>
<div><em>Show of hands:<br/></em> People who have looked at project history</div>
<p>
Who here has ever looked at a project's history?
Maybe you were troubleshooting a bug;
Maybe you were looking for an explanation
Maybe you were doing a code review
(Nearly Unanimous!)
</p>
<div>Why?</div>
<p>
Why (for what purposes) have you looked at source control history?
+ Compare changes to avoid conflicts
+ Figure out what changed to troubleshoot bugs
+ Look at a previous commit to find out what went into a feature
+ Who wrote this line of code so I can ask them a question?
+ Code Quality: every time you do a pull request, you look at history!
</p>
<div class="center">Repository of <em>Knowledge</em></div>
<p>
Source control history is Repository of Knowledge,
not just of code.
</p>
<div>Code tells you what changed and <em>how</em></div>
<div>Great commit messages tell you what changed <em>why</em></div>
<p>
The secret to writing great commit messages is
to share knowledge,
and to explain WHY. Also What.
If you do this, you will impart the following benefits
to future you and your whole team:
</p>
<div>Switch contexts <em>faster</em></div>
<div>Make <em>well-informed</em> decisions</div>
<div>Make them <em>quicker</em></div>
<p>
If your commit messages explain why,
+ You can switch contexts faster
+ Your decisions will be well-informed
+ You can make decisions quicker
In other words:
</p>
<div>Less time <em>seeking</em> answers</div>
<div>More time <em>creating</em> answers</div>
<p>
Basically, you spend less time seeking answers
and more time creating them.
In order to do that, we need a standard for
conveying information in the git history
</p>
<div>7 Rules of <em>Great</em> Commit Messages</div>
<p>
I did not come up with these, but I like them.
So does everybody else on the whole internet.
BUT FIRST, an example:
</p>
<div><img src="./great_commit.PNG"></div>
<p> The first FIVE deal with the subject line. </p>
<div><em>1.</em> Separate subject from body with a blank line</div>
<div><em>2.</em> Limit the subject line to 50 characters</div>
<div><em>3.</em> Capitalize the subject line</div>
<div><em>4.</em> Do not end the subject line with a period</div>
<div><em>5.</em> Use the imperative mood in the subject line</div>
<div><em>6.</em> Wrap the body at 72 characters</div>
<div><em>7.</em> Use the body to explain what and why vs. how</div>
<div><img src="./great_commit.PNG"></div>
<div>How to make <em>great</em> commit messages?</div>
<div>Think about your <em>Audience</em></div>
<div>Your teammates</div>
<div>Future developers</div>
<div>Future <em>you</em></div>
<div><em>Empower</em> them to make the <em>best</em> decisions</div>
<div>Suggestions:</div>
<div>Tag issues / Add URLs in the description</div>
<p>
Give context to the changes you're making.
If you're working on a story logged in Rally or Github,
specifying the issue number will help future developers
understand the story behind your changes.
</p>
<div>Explain Motivation</div>
<p>
This can sometimes be self-explanatory, but it never hurts to provide context
"Remove trailing commas to fix JSHint" as opposed to just "Remove trailing commas"
The benefit with this is that we can begin to index and analyze the time/commits
invested in certain subjects
</p>
<div>Explain Tradeoffs</div>
<p>
Software development is a constant exercise in picking from a set of tradeoffs.
When modifying a piece of code,
knowing the tradeoffs at play can save time and effort,
resulting in higher quality software
</p>
<div>Explain Other Approaches</div>
<p>
This gives future developers more context to make
informed decisions about changes to the code
This is especially helpful when tradeoffs are being made
"in the interest of time"
</p>
<div>Discuss Difficulties</div>
<p>
This information may help future developers who run into similar problems,
and may also facilitate discussions about tradeoffs
</p>
<div>Mention relevant commits</div>
<p>
When fixing bugs or removing old code,
Sticking the hash in the commit message can help close the loop
If issues with YOUR code come up
EX: Trying to increase max zoom level in stacks
</p>
<div>Take <em>pride</em> in your messages!</div>
<p>
You're doing yourself and your team a favor;
you should be proud of that!
An investment in quality commit messages will pay dividends in
</p>
<div><em>Great</em> commit messages will:</div>
<div>Pay dividends in <em>speed</em></div>
<div>Pay dividends in <em>quality</em></div>
<div>Pay dividends in <em>productivity</em></div>
<div>Pay dividends in <em>CA$H MONEY</em></div>
<div>Bring the Future here <em>faster</em></div>
<div>Write <em>great</em> commit messages</div>
<div class="center">Thank You</div>
<div>
<em>1.</em> Separate subject from body with a blank line<br/>
<em>2.</em> Limit the subject line to 50 characters</br>
<em>3.</em> Capitalize the subject line</br>
<em>4.</em> Do not end the subject line with a period</br>
<em>5.</em> Use the imperative mood in the subject line</br>
<em>6.</em> Wrap the body at 72 characters</br>
<em>7.</em> Use the body to explain what and why vs. how
</div>