Commits / Writing a good commit message

When you commit a change in git, you are assigning a change to a message. The change is controlled when you add the files into the commit, but the message is the only bit that can’t be automated.

1.1 Capture ‘why’, and not ‘what’

The easiest way to write a good commit message is to say why the code is changing.

The change :

diff --git a/README.md b/README.md
index 42911de1..7c535bf0 100644
--- a/README.md
+++ b/README.md
@@ -6,15 +6,16 @@
 
 2. Run `bin/build` & go make some tea (it'll take a while)
 
-3. Acquire a recent dump of the database, and place it in `tmp/dump.sql`
+3. Acquire a recent dump of the database, and place it in the project directory `./tmp/dump.sql`
 
 4. Run the project in the foreground with `bin/start`. The first time you start the app, you might see the server restarting a few times until it connect to the Mysql database. This is normal, the SQL dump is just taking time to import.
 
-5. In a new terminal, setup a new admin user: `bin/new-user` (the password will only survive the first login)
+5. In a new terminal, setup a new admin user: `bin/new-user`
+  The password will only survive the first login, and it has quite strict validity, so be prepared to have to change it a few times!
 
 6. Navigate to http://localhost:7000/admin
 
-7. Once it's setup, remove or rename `tmp/dump.sql` file, otherwise your data will be wiped on the next build.
+7. Once it's setup, remove or rename `./tmp/dump.sql` file, otherwise your data will be wiped on the next build.
 
 ### Stopping the containers

A good message

commit fb8717c3 
Author: Andy Callaghan <[email protected]>
Date:   Wed Mar 6 11:41:39 2019 +0000

    Updated Readme following Alina’s review
    
    The tmp/dump.sql file was ambiguous as to where to place it, so made it clearer.
  • 😀 Says why the change was made
  • 😀 Easier to search for later
  • 😀 Name dropping (for later blaming that person)

A bad message

commit fb8717c3
Author: Andy Callaghan <[email protected]>
Date:   Wed Mar 6 11:41:39 2019 +0000

    Updated Readme
  • 🤨 We already know this from the diff
  • 🤨 Tells us nothing about what actually changed

Commit best-practice

Keep commits small and atomic. They should represent the smallest change that can be grouped together.

* c9679ddc (HEAD -> fix-admin-spec-examples) Tidy up whitespace
* 279a6efb Wrap the example with time cop block
* 9112118d Make admin spec - assert an admin model is created

For instance in the example above - the Tidy up whitespace commit is seperated from the functional commits. It’s important to do the tidying, but having it cloud up other commits with functional changes, especially if they’re across multiple files will make your job hard later.

By keeping commits smaller, and more descriptive, we document the code changes properly. This makes changes to these files easier in the future, and it becomes a layer of documentation that will be invaluable.


Now we’ve seen how to write a good commit message, we can read about cherry picking commits