git-course/04-commit-advice.html at gh-pages · monishanatchiar/git-course · GitHub

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
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <meta name="generator" content="pandoc">
    <title>UoM Research IT training: Version control with Git</title>
    <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" type="text/css" href="css/bootstrap/bootstrap.css" />
    <link rel="stylesheet" type="text/css" href="css/bootstrap/bootstrap-theme.css" />
    <link rel="stylesheet" type="text/css" href="css/swc.css" />
    <link rel="alternate" type="application/rss+xml" title="Software Carpentry Blog" href="http://software-carpentry.org/feed.xml"/>
    <meta charset="UTF-8" />
    <!-- HTML5 shim, for IE6-8 support of HTML5 elements -->
    <!--[if lt IE 9]>
      <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
  </head>
  <body class="lesson">
    <div class="container card">
      <div class="banner">
        <!a href="http://software-carpentry.org" title="Software Carpentry">
          <!img alt="Software Carpentry banner" src="img/software-carpentry-banner.png" />
        <!/a>
        <a href="http://www.itservices.manchester.ac.uk/" title="University Of Manchester">
          <img alt="UoM banner" src="img/university-of-manchester-banner.png" />
        </a>
      </div>
      <article>
      <div class="row">
        <div class="col-md-10 col-md-offset-1">
                    <a href="index.html"><h1 class="title">Version control with Git</h1></a>
          <h2 class="subtitle">How, what and when to commit</h2>
          <section class="objectives panel panel-warning">
<div class="panel-heading">
<h2><span class="glyphicon glyphicon-certificate"></span>Learning objectives</h2>
</div>
<div class="panel-body">
<ul>
<li>Understand what makes a good commit message</li>
<li>Know which types of files not to commit</li>
<li>Know when to commit changes</li>
</ul>
</div>
</section>
<h3 id="how-to-write-a-good-commit-message">How to write a good commit message</h3>
<p>Commit messages should explain why you have made your changes. They should mean something to others who may read them - including your future self in 6 months from now.</p>
<p><a href="http://chris.beams.io/posts/git-commit/">Here is an excellent summary</a> of best-practice. It’s well worth a read but the key points are given below:</p>
<ol style="list-style-type: decimal">
<li>Separate the subject from body with a blank line</li>
<li>Limit the subject line to 50 characters</li>
<li>Capitalize the subject line</li>
<li>Do not end the subject line with a period</li>
<li>Use the imperative mood in the subject line</li>
<li>Wrap the body at 72 characters</li>
<li>Use the body to explain what and why vs. how</li>
</ol>
<hr />
<h3 id="commit-anything-that-cannot-be-automatically-recreated">Commit anything that cannot be automatically recreated</h3>
<p>Typically we use version control to save anything that we create manually e.g. source code, scripts, notes, plain-text documents, LaTeX documents. Anything that we create using a compiler or a tool e.g. object files (<code>.o</code>, <code>.a</code>, <code>.class</code>, <code>.pdf</code>, <code>.dvi</code> etc), binaries (<code>exe</code> files), libraries (<code>dll</code> or <code>jar</code> files) we don’t save as we can recreate it from the source. Adopting this approach also means there’s no risk of the auto-generated files becoming out of sync with the manual ones.</p>
<hr />
<h3 id="when-to-commit-changes">When to commit changes?</h3>
<p>There are no hard and fast rules, but good commits are atomic - they are the smallest change that remain meaningful.</p>
<p>In the same way that it is wise to frequently save a document that you are working on, so too is it wise to save numerous revisions of your files. More frequent commits increase the granularity of your “undo” button.</p>
<p>While DropBox and GoogleDrive also preserve every version, they delete old versions after 30 days, or, for GoogleDrive, 100 revisions. DropBox allows for old versions to be stored for longer but you have to pay for this. Using revision control the only bound is how much space you have!</p>
<p>For code, it’s useful to commit changes that can be reviewed by someone else in under an hour.</p>
<hr />
<blockquote>
<p><strong>What we know about software development - code reviews work</strong></p>
<p>Fagan (1976) discovered that a rigorous inspection can remove 60-90% of errors before the first test is run. <a href="http://www.mfagan.com/pdfs/ibmfagan.pdf">Design and Code inspections to reduce errors in program development</a>. IBM Systems Journal 15 (3): pp. 182-211.</p>
<p><strong>What we know about software development - code reviews should be about 60 minutes long</strong></p>
<p>Cohen (2006) discovered that all the value of a code review comes within the first hour, after which reviewers can become exhausted and the issues they find become ever more trivial. <a href="http://smartbear.com/SmartBear/media/pdfs/best-kept-secrets-of-peer-code-review.pdf">Best Kept Secrets of Peer Code Review</a>. SmartBear, 2006. ISBN-10: 1599160676. ISBN-13: 978-1599160672.</p>
</blockquote>
<hr />
<p>Previous: <a href="03-history.html">Looking at history and differences</a> Next: <a href="05-branching.html">Branching, merging and resolving conflicts</a></p>
        </div>
      </div>
      </article>
      <div class="footer">
        <a class="label swc-blue-bg" href="http://software-carpentry.org">Software Carpentry</a>
        <a class="label swc-blue-bg" href="https://github.com/gcapes/git-course">Source</a>
        <a class="label swc-blue-bg" href="mailto:research-it-training@manchester.ac.uk">Contact</a>
        <a class="label swc-blue-bg" href="LICENSE.html">License</a>
      </div>
    </div>
    <!-- Javascript placed at the end of the document so the pages load faster -->
    <script src="http://software-carpentry.org/v5/js/jquery-1.9.1.min.js"></script>
    <script src="css/bootstrap/bootstrap-js/bootstrap.js"></script>
    <script src='https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'></script>
  </body>
</html>