Skip to content

Commit

Permalink
Add great_commit_messages.html slides and speaking notes
Browse files Browse the repository at this point in the history
  • Loading branch information
@owap
owap committed Aug 9, 2016
1 parent 4729e3c commit 5f80047
Show file tree
Hide file tree
Showing 2 changed files with 323 additions and 2 deletions.
9 changes: 7 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ use Git at BlackSky. The resources are as follows:
+ `slides.md` - A simple set of slides to accompany the lesson plan above
+ `crash_course.html` - The file you open in the browser to view the slides
+ `index.html` - The playground in which we will practice our git-fu
+ `great_commit_messages.html` - Another set of slides + speaking notes on the
importance of writing great commit messages.

## Self Study
If you are interested in **learning git**, the [Git Immersion](http://gitimmersion.com/)
Expand All @@ -20,8 +22,8 @@ convince you of the importance of writing good commit messages. :)

# Updating Slides
If you find you have become the person in charge of the Git Crash Course
contained herein, you may be interested in updating the slides. The slides are
written in markdown, and you can compile them to HTML with [biggie](https://github.com/tmcw/biggie).
contained herein, you may be interested in updating the slides. The crash course
slides are written in markdown, and you can compile them to HTML with [biggie](https://github.com/tmcw/biggie).

1. Install biggie:
```
Expand All @@ -32,3 +34,6 @@ npm install -g biggie
```
biggie slides.md --style ./resources/big_styles.css > crash_course.html
```

The slides for `great_commit_messages` were painstaking crafted by hand in raw
HTML, so you'll have to forego Markup when editing those.
316 changes: 316 additions & 0 deletions great_commit_messages.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,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>

0 comments on commit 5f80047

Please sign in to comment.