DEV Community: Scott Johnson

How I Write a Commit Message

Scott Johnson — Wed, 26 Jun 2019 16:01:27 +0000

Introduction

This is a topic that has been covered at length in other blog posts (most notably Chris Beams' blog post), but it's important, so it bears repeating. When you're working on a large software project, it makes everyone's life (including yours) much easier if you write consistent, descriptive, and easily readable commit messages.

Software engineering is tough. You spend all day (or multiple days) getting your feature/bug fix mapped out, writing the code, debugging said code, writing tests to verify that nothing is broken in the future, and then, after all of that, you have to craft your commit(s). It's very tempting to let your discipline lapse and just write something half-baked without thinking too much about it, just so you can get that task into the "Done" state.

Here's the kicker, though: someday, you're likely going to have to go back and review that commit message. If, for no other reason, you may want to go through your git repository to see what you've accomplished since your last performance review. Going through a git commit log like this (Yeah, this is a real snippet from a commit log that I wrote. The worst part is that those commit messages are all there is. There's no additional description in any of them):

85dd75c refactor interfaces so they are all in the same format
2af1c6d add code for branching model
d3b2606 Merge branch 'glsl'
3a6bed2 add necessary graphics libraries
d028509 fix issue #17261
2367d80 more work toward full implementation
2067b23 add cpp files
a111bff makefile generation
14a715e create repo

Is much more work than going through a commit log like this:

61c70bc Add a configuration to ripsaw.
8af4151 Merge pull request #7 from jwir3/jwir3/#3-cut-list
9d05854 Add a CutList data structure.
74a21ae Merge pull request #5 from jwir3/main-ui
4be2728 Add a basic user interface for binary program.
de4061d Refactor measurements functionality into its own rust file.
15cc8e1 Merge pull request #1 from jwir3/basics
a6c6010 Add the ability to create nominal and actual lumber sizes.
6a1e1fd Initial commit

I can tell exactly what was changed in each of the commit messages from the latter example.

Moreover, this is your work. You've put in the hours necessary to make this code work. The git commit message is your advertisement of the work you've accomplished. It's the thing most of your colleagues are going to see that has your name attached, since, as we're working in code from day-to-day, we typically see the code, not the person who wrote it. Take pride in your work - this is your opportunity to "sell" it to your colleagues!

The Rules

There are three basic rules I follow (with an additional, optional one at the very beginning):

(Optional) Choose a gitmoji to represent your commit
Add a simple subject in the imperative mood, starting with a capital letter, no more than 80 characters in length, and separated from the body by a blank line.
Write a body message describing what was accomplished in the commit, as well as why it was necessary, wrapped at 80 characters in length, separated from the metadata with a blank line.
Add all metadata (e.g. ticket numbers, CI commands, etc...) at the end of the commit message.

Choose a gitmoji to represent your commit

I've found that reading commit logs (especially one-line logs) can be made much simpler with an emoji that describes the category of change that the commit falls under. I personally use gitmoji, an informal standard for which types of commits use which emoji, but you can really use anything you want, as long as you're consistent.

By adding something like 🐛 before your commit, it's pretty clear every time you read it that this commit fixed a bug. I find it helps with parsing, but you have to be willing to add some helper packages so that git log works on the command line.

Add a simple subject

In the manpage for git-commit, the following argument is made:

DISCUSSION
Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used throughout Git. For example, git-format-patch(1) turns a commit into email, and it uses the title on the Subject line and the rest of the commit in the body.

I've personally found that 50 characters is a little short, although, I can see the point if you're reviewing patches via email. Github seems to truncate the subject line of a commit at 72 characters, so that's worth keeping in mind, too. I set my vim editor (which is what I use to write commit messages) to show a vertical line and automatically add a newline at 80 characters. It's somewhat of an arbitrary limit, but I don't think that 50 or 72 characters is quite enough, personally, and 80 character line limits seem to be a standard.

I think the idea behind the 50 character limit is that when in a terminal with an 80 character line length limit, the sha of the commit and it's trailing space require 10 characters on average, but they can require up to 41 characters (40 for the sha itself, plus 1 for the space), thus you really only have 80 - 41 = 39 characters of actual message length. I think, though, that most terminals aren't limited to 80 characters anymore, so this is somewhat moot. Instead, it's a discipline thing: you should be disciplined enough as an engineer to be able to summarize your changes in 50 characters or less.

That said, here's my argument against limiting yourself to 50 characters: first off, we live in a society that is becoming more and more conditioned to brief communications (think news headlines and tweets). In most cases, the ideal spot for a news headline is 60-100 characters [^2]. 80 characters is a good middle ground in that range for people to be able to digest.

A commit subject should be in the imperative mood. What this essentially means is that it should complete the sentence " When this commit is applied, it will ___________________. Think about how easy to read this is when it's properly written in this manner. It also helps you, as an engineer crafting the commit, to know if you've overstepped the bounds of a commit changing a single related and cohesive thing, rather than changing a bunch of things that are unrelated.

One other detail about the subject that might be controversial: I actually add a period to the end of my commit messages. The reason I do this is because, in my opinion, the subject line of the commit should be a complete sentence. I find messages easier to read and parse when proper punctuation is used, but this is just me.

Write a body message

It's important to add descriptive data as to what, specifically, was changed in your commit (beyond the limit of your subject line). I've found, though, that more important is the justification for this change. In six months, you might come back to this commit, realize that you changed a file or a class, but you might not remember why that change was necessary. The body also gives you room to express yourself using lists, bullets, links, or, in some cases (depending on your organization's policies) full markdown.

It is worth noting that not every commit requires a subject line and a body. Sometimes, if the subject line is absolutely clear, it's worth just leaving the body blank. I also do this if it's a merge commit, but I will sometimes add the metadata section to indicate who reviewed my merge:

commit a2f525f01bf657b706fd2f39bbf704aa7b9c4a69
Merge: d9f74c1fd 4530a7243
Author: Scott Johnson <jaywir3@gmail.com>
Date: Mon May 13 16:22:45 2019 -0500

    Merge pull request #5616 from jwir3/bump-versions-package-may19

    [r=VerteDinde, coreh]

Add all metadata at the end of the commit message

We all have things that we need to add to a commit - ticket numbers, references to other commits, who reviewed a given commit, etc... This metadata should be placed at the end of the commit message. The rationale for this is that this tends to be things that are either required by a continuous integration system (e.g. it should be machine-readable, rather than human-readable), or is ancillary information not directly related to the commit in question (i.e. if your commit is readable enough, why bother going to the original ticket for more information? You should be able to find the answer to your question within the git log itself).

Thus, I tend to organize my data in a commit in a linear fashion, with the information I'm most likely to want coming first, in this order:

What category this commit fits into
What this commit changes
A thorough explanation of what was changed and why it was necessary
Any ancillary metadata that helps me locate more information if this wasn't enough

A Config to Help You

I find the following commit template configuration helpful as a reminder of this. Just put the file into ~/.gitmessage and it will show up for you every time you enter the editor after running git commit:

# When applied, this commit will:

# This change is necessary because:

# The following is metadata for this commit:

How can I get my organization to do this?

There's a small part of this that I've glossed over that makes this all worthwhile. It's only somewhat beneficial if you're the only one in your organization doing this. How can you get engineers from across the organization writing commits like this?

Part of the answer to this questions is: You can't. It's not possible to control other people's behavior completely, so you should temper your expectations. People will do things that they believe have value, so if they don't think that writing commit messages in this way has value, they won't do it. There are ways to encourage them to see value in it, though.

I've found that around 85% of organizations I've been a part of don't have any documentation on how to write commit messages. If, however, your organization is part of the 15% that does have a standardized way of writing commit messages, by all means, follow those rules. Otherwise, what I do is to keep in mind a couple of things:

The other person isn't you. They have different expectations from their higher-ups (and themselves), so it's not a great idea to try to force upon them a standard that you simply create out of thin air.
Some small things (like the difference between an 80-character subject line and a 50-character subject line) are ideological battles that aren't worth fighting over. If that's the sticking point between you and a colleague, just let them do it however they want, as long as the benefit is still present.

Now, on to the techniques for encouraging this behavior. I find that core review and micro-rewards are a great way to encourage the writing of great commit messages. Most organizations have some form of code review process. This is a great place to enforce commit message practices. One thing to be careful about, though, is to not become too dictatorial. If I see a commit message that could be improved during a code review, I will often consider re-writing the commit message for the person in question, and posting that as a suggested change in the code review. Additionally, not everyone knows how to use git rebase (see also Rebasing Toward Independence), so it's worth it to add a comment detailing how they change their commit message in the code review, as well.

Keep in mind that you can always suggest the change be made, but unless the commit message is really nondescriptive, I typically wouldn't hold up a code review solely on that front. Over time, it will become clear in the log which engineers take the time to write a good commit message and which ones don't. Once other engineers are onboard and have to work with the commit messages another person is creating, peer pressure will eventually win out.

The other option that I use is micro-rewards. This is specific to an individual company, but some companies utilize a platform like bonus.ly to enable employees to reward each other over the course of a month. If I see a commit message that really stands out in a good way, I'll go out of my way to reward that individual publicly so that everyone knows I appreciate that.

The downside to this, of course, is that your company needs to subscribe to the service in order for you to do this. You can, however, bring good commits up during retrospective meetings, during stand-ups, or even just in Slack on a good day, complimenting someone publicly about their commit messages. Stay away from chastising people who aren't doing what you want publicly, as that doesn't tend to work well in getting people to change their behavior, and usually makes you look bad.

In all, you can't force someone to do what you want them to do, but you can encourage the path you think is the correct one.

Rust and Wasm Side-by-Side

Scott Johnson — Fri, 26 Oct 2018 15:42:57 +0000

Background

At my work, we're considering using WebAssembly (hereafter abbreviated as WASM) because it allows us to cross-compile just about any language for use on the web. WebAssembly is a "binary instruction format for a stack-based virtual machine". Basically, this means it's a binary language designed to be run anywhere, but generally speaking, it's used right now within web browsers as a replacement for Javascript modules. One of the languages we are considering using as a source language is Rust, a new(ish) language designed for type safety, performance, and concurrency.

As such, I've been reading up the Rust programming language, and, more importantly, how to compile Rust to WebAssembly. After learning from the example module given in the RustWasm book, I decided to convert one of my personal npm libraries from JS -> Rust ^[1]. The first step in this endeavor was to convert over the existing tests that I had in mocha/chai to Rust's native test format, so that as I added code, I could verify that it was working as I expected it to work ^[2]. However, the ability to run these tests became an issue when I moved to a WASM target.

The Problem

One of the big downsides to compiling Rust to WASM is that there isn't a good way to debug code within the browser, and have it link back to the Rust source. The Rust-WASM book notes this in the section on debugging:

Unfortunately, the debugging story for WebAssembly is still immature. On most Unix systems, DWARF is used to encode the information that a debugger needs to provide source-level inspection of a running program. There is an alternative format that encodes similar information on Windows. Currently, there is no equivalent for WebAssembly.

Instead, they recommend using testing (specifically, automated testing) to identify regressions before they make it into the build. This is a great idea, and one I obviously support, given my original writing of tests prior to implementing my library. However, there's one big downside to writing tests in Rust when compiling to WASM, as detailed in the next subsection of the Rust-WASM book:

Note that in order to run the #[test]s without compiler and linker errors, you will need to comment out the crate-type = "cdylib" bits in wasm-game-of-life/Cargo.toml.

Wait... what? In order to run my Rust tests, I need to make changes to my source repository just to get it to build? This is a bit of a non-starter for me, because I want to run on a continuous integration system, where I'm able to build the Rust package, run the tests, build the WASM binary, and then deploy to NPM, all automatically.

In other words, what I want to be able to do is something like this:

# These commands compile (and subsequently test) the native Rust code
$ cargo build
$ cargo test

# This command builds the wasm module
$ cargo build --target=wasm32-unknown-unknown

The key here, though, is that I want to be able to do this without making any source file or build-file changes.

Possible Solutions^[3]

I spent quite a bit of time trying to determine what I could do here. One thought that came to mind was that I could have a pre-build script that runs that performs this commenting-out of #[wasm_bindgen] attributes manually. How this would work is, before building, the script would make copies of everything in the local directory to a sub-directory. It would then switch the crate-type in subdirectory/Cargo.toml to lib, instead of cdylib and comment out any instances of #[wasm_bindgen]. Needless to say, I didn't want to go this route - it seemed incredibly fragile and error-prone.

Next, a coworker of mine suggested I separate the native Rust code from the WASM aspect of the code, and make the WASM library utilize the code from the native library, similar to how geotoy handles this^[4]. This is a great solution, but, when I set up my library, I couldn't for the life of me figure out how to import an enum or struct into the WASM portion of the library.

Basically, geotoy has a setup where it uses the WASM library to expose a set of functions that serve as the API for the library. These functions then utilize the data structures in src/lib.rs. However, the data structures themselves aren't exposed. With cratchit, what I want to expose is the Account and AccountsChart data structures, as well as the Currency and AccountType enumerations directly, instead of a set of gateway functions that utilize these data structures ^[5]. I suspect there probably is a way to get it to expose the structs, but I wasn't able to figure it out.

Final Solution

The solution I eventually arrived at doesn't separate the libraries per se. Instead, it makes the #[wasm_bindgen] attributes conditional on whether or not you're building for a WASM target.

The first thing you need to do is make sure you're using both cdylib and rlib (or lib) in your Cargo.toml:

[lib]
crate-type = ["cdylib", "rlib"]

Next, (this might be specific to me), I had to add #![feature(custom_attribute)] to the top of my crate attributes (i.e. at the top of src/lib.rs:

#![feature(custom_attribute)]

extern crate cfg_if;
extern crate json;
extern crate wasm_bindgen;

use wasm_bindgen::prelude::*;
use cfg_if::cfg_if;
use std::collections::HashMap;

...

Next, wherever you previously used #[wasm_bindgen], make it conditional on the target architecture:

/// Use this instead of #[wasm_bindgen]
#[cfg_attr(target_arch = "wasm32", wasm_bindgen)]

Finally, and this might, again, be something that is specific to my use case, you need to pull types out of submodules and into the root crate src/lib.rs. In other words, in my src/lib.rs, I had the following:

pub mod accounts;
pub mod currency;

And I had two files, src/currency.rs and src/accounts.rs, which defined types related to accounts and currencies, respectively. wasm_bindgen didn't appear to like this, so I moved this code into src/lib.rs and removed references to the modules in the tests.

What I did to test was not use wasm-pack initially. Instead, I ran cargo +nightly build --target=wasm32-unknown-unknown to ensure that no errors were present, and that it created a .wasm file in the appropriate target directory:

$ cargo +nightly build --target=wasm32-unknown-unknown
...
$ ls -al target/wasm32-unknown-unknown/debug
total 9520
drwxr-xr-x@ 13 scottj staff 416 Oct 26 10:15 .
drwxr-xr-x 3 scottj staff 96 Oct 26 10:14 ..
-rw-r--r-- 1 scottj staff 0 Oct 26 10:14 .cargo-lock
drwxr-xr-x 8 scottj staff 256 Oct 26 10:14 .fingerprint
drwxr-xr-x 3 scottj staff 96 Oct 26 10:14 build
-rw-r--r-- 1 scottj staff 122 Oct 26 10:15 cratchit.d
-rwxr-xr-x 2 scottj staff 3549051 Oct 26 10:15 cratchit.wasm
drwxr-xr-x 13 scottj staff 416 Oct 26 10:15 deps
drwxr-xr-x 2 scottj staff 64 Oct 26 10:14 examples
drwxr-xr-x 3 scottj staff 96 Oct 26 10:15 incremental
-rw-r--r-- 1 scottj staff 125 Oct 26 10:15 libcratchit.d
-rw-r--r-- 2 scottj staff 1311774 Oct 26 10:15 libcratchit.rlib
drwxr-xr-x 2 scottj staff 64 Oct 26 10:14 native

And, of course, I made sure the tests ran without any changes:

$ cargo test
running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

     Running target/debug/deps/test_accounts-54475044840749bd

running 6 tests
test account_type_from_integer ... ok
test account_creation ... ok
test account_type_from_string ... ok
test adding_top_level_accounts_to_accounts_chart ... ok
test getting_all_account_ids_in_a_chart ... ok
test creating_accounts_chart_from_json ... ok

test result: ok. 6 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

     Running target/debug/deps/test_currency-d2d59a6d3436c103

running 1 test
test currency_translation_from_string ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

   Doc-tests cratchit

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Now, when you want to build your WASM module, you can run:

wasm-pack build

And, it will create the packaged WASM library for you in pkg.

Bonus: Run tests on Travis and deploy WASM to NPM

This was another area that took a bit of figuring out for me. The problem I ran into with Travis-CI was that it doesn't install wasm-pack by default. As such, you need to install it manually in a script. However, if you have cache: cargo enabled, it will hang if wasm-pack was previously installed. Thus, I added the following to my .travis.yml file to conditionally install wasm-pack:

before_script: |
  if hash wasm-pack 2>/dev/null; then
      echo "Wasm-pack already is installed"
  else
      curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
  fi

Now, you can add the following to your script section build both the WASM module and the native Rust module:

script:
- cargo clean
- cargo build
- cargo test
- wasm-pack build --target=nodejs

Note the section that calls wasm-pack build has an additional argument: --target=nodejs. If you want to test locally using npm link, you will need this argument, since it packages the WASM module with a main parameter in the package.json.

And, finally, add the deployment logic^[6]:

before_deploy:
- cd pkg
deploy:
  provider: npm
  email: <your email address>
  on:
    tags: true
  skip_cleanup: true
  api_key:
    secure: <YOUR_API_KEY>

Note that this deployment logic will only deploy on tagged releases, so you may want to change that if you want different behavior.

One last thing to realize: this currently requires nightly rust. So, you'll need to make sure you're using nightly Rust locally, and you need to make sure that, if you're building on travis, that you allow stable and beta Rust to fail:

rust:
- stable
- beta
- nightly
matrix:
  allow_failures:
    - rust: stable
    - rust: beta

The library in question is Cratchit, which is a library designed to encapsulate accounting data for an accounting application running in electron. It's not important that you have familiarity with this library, but if you want to follow along, feel free. ↩︎
I'm going to gloss over the rest of the adventures regarding me porting to Rust, since it's not super interesting, and involves me fighting a lot with the borrow checker to get things to work. ↩︎
If you're not interested in my musings about the problem and how I came to the solution, feel free to skip to the section on the solution I used, later on in this post. ↩︎
The coworker in question is Johannes Hoff who also is a contributer on the geotoy repo. Interestingly enough, the original author of geotoy, Nick Fitzgerald, was an intern at Mozilla when I first started there. It's amazing to me sometimes how small this world is, given that I haven't seen fitzgen in years, and one of my coworkers happens to have a solution to a problem I have, in collaboration with this other person I worked closely with. Sometimes the wheel of fate astounds me. ↩︎
There probably is a good reason for exposing gateway functions, rather than the underlying data structures themselves, which I will discover at some future point, but for now, my chosen solution seems to be a little cleaner. ↩︎
Make sure that you encrypt your api key. You can do this by retrieving an api key from travis-ci.org and then running: travis encrypt <api_key> --add deploy.api_key. I waited until I had the configuration otherwise the way I wanted it before doing this. ↩︎

git bisect: A Gentle Introduction

Scott Johnson — Wed, 31 Jan 2018 01:19:43 +0000

Motivation

Imagine this situation: You're a software developer who's just been assigned a ticket. It's a bug, and the symptom of the problem is that your app is rendering triangles where it should be rendering quadrilaterals.

Seems straightforward enough, right? But wait - you are actually given more information. This is a regression, which means that the app used to correctly render quadrilaterals, and now it's rendering them as triangles. Whenever a software engineer sees a regression, the first thought should be "When was the first time this error exhibited itself?" If you ask the person that filed the bug, you'll probably get an answer like this:

Why is this question important, anyway? Well, if we can isolate the change where the regression first appeared, we know that the error was in the code that was added or removed when that change was applied.

git bisect

git bisect is a tool you can use to run a binary search ^[1] on a set of commits to (hopefully) determine which one first exhibited the problem. It's a powerful tool, but there's a catch: you have to have a linear history of independently buildable, small, and working changes in order for it to work in the best manner possible ^[2].

Prerequisites

git (which you probably already know or you wouldn't be reading this post) is a tool for controlling revisions of files. You edit files, then commit them to the repository after validating your changes. git keeps track of the history of these commit objects, effectively building a graph.

In the ideal case, your commit history looks something like this:

Unfortunately, through bad commit/merge practices, you can sometimes get into a situation where this history is nonlinear:

Fixing a history that is non-linear is beyond the scope of this blog post, but if you're in this situation, you might want to check out ^[3] for some guidance. ^[4]

One other important prerequisite is that the regression is reproducible. If you don't have a regression that's consistently reproducible, you can't test it at each stage. git bisect relies on the fact that the regression can be tested for at each step in the process.

The bisect process

Basics

git bisect works like this: given an input range of commits, it splits the range in which the regression occurred into two sections using a commit near the center of the range. It checks out this pivot revision, and based on your input, it determines which of the two ranges on either side of the pivot should be checked next.

In the diagram above, you can see that we have a known "good" commit, a known "bad" commit (usually this is HEAD, as the regression presumably exists at the current head of the master branch, otherwise you probably wouldn't need to fix it ^[5]), and some unknown point where the regression was introduced.

There are really only four commands you need to know to use git bisect:

git bisect good
git bisect bad
git bisect skip
git bisect reset

Starting a Bisect

You can start a bisect session with git bisect start ^[6]:

scottj|jwir3/master:~/Source/SinkingMoon/website$ git bisect start
scottj|jwir3/master|BISECTING:~/Source/SinkingMoon/website$

But, wait... git bisect start wasn't on the list of commands I said you needed to know. That's because if you run one of the other commands, git will offer to start the process for you:

scottj|master:~/Source/SinkingMoon/website$ git bisect bad
You need to start by "git bisect start"
Do you want me to do it for you [Y/n]? y
scottj|master|BISECTING:~/Source/SinkingMoon/website$

Marking a Commit

While bisecting, git keeps track of the state of each commit. Each commit could be "good" (i.e. the regression is not present in this commit), "bad" (i.e. the regression is present in this commit), or "unknown" (i.e. there isn't enough information to determine whether the regression is present in this commit) To mark the current commit as "good", use git bisect good. Alternatively, to mark it as "bad", use git bisect bad. You can also mark a commit that isn't the current commit as "good" or "bad" by adding the commit hash to the end of the command, as in git bisect bad <hash>.

Once you have marked both a "good" and "bad" commit, git bisect will check out a commit near the middle of the range and prompt you to test this commit for the presence of the regression:

scottj|master:~/Source/SinkingMoon/website$ git bisect bad
You need to start by "git bisect start"
Do you want me to do it for you [Y/n]? y
scottj|master|BISECTING:~/Source/SinkingMoon/website$ git bisect good c3a736
Bisecting: 12 revisions left to test after this (roughly 4 steps)
[f2fd95cc92fa63a8a1a38a2ff2a8ccd406286849] Add handling for shapes that were previously considered non-primitive.
scottj|(f2fd95c...)|BISECTING:~/Source/SinkingMoon/website$

As you can see, git bisect tells you how many commits are in the range, and about how many manual tests you're going to have to perform to find the regression.

What you do now is check to see if the regression is in the currently checked-out commit, using whatever process you have available. If the regression is present in the currently checked-out commit, mark it as "bad" with git bisect bad. If it's not, then mark it with git bisect good.

There's a special situation that happens when you have a commit that you can't test^[7] - you have to skip it using git bisect skip. You should refrain from overusing git bisect skip, because if the actual regression happens to fall next to a commit that was skipped, you end up with a range of commits that could have caused the regression, and git bisect won't be able to help you any further than that.

Going back to the output, we see that the next commit to be tested is f2fd95, but this wasn't on our chart. How can this be the case? The reason this happens is that git bisect will automatically look through the commits in merged branches:

As you keep repeating this process, eventually you will reach a point where all of the commits are either marked or skipped:

git bisect will report the first commit that contains the regression in a manner like so:

commit a73eed9a145bea5c05833f33eb26eec6

Author: Scott Johnson <jaywir3@gmail.com>
Date: Sat May 20 18:44:29 2017 -0500

    Subdivide all polygons into triangles using ear-clipping algorithm.

    Fixes #817.

Now, you can use git diff a73eed..a73eed^ to see all of the changes in the commit and (hopefully) determine the source of the regression! ^[8]

Resetting a Bad Bisect

From time to time, you get into a situation where the bisect didn't work properly, or you screwed up along the way without realizing it. If this happens, use git bisect reset. This will terminate the bisect process, and check out the last revision you had checked out before you started git bisect.

If you accidentally mark a commit as "bad" when it should have been "good" (or vice versa), it's kind of wonky to get back to the state where you want to be. You can't just check out that commit and then set it to whatever you want (git will report Commit XXXXXXX is both good and bad). What you need to do is output the log to a file, change the one you need to change, and then replay the log back using git bisect.

Suppose we accidentally marked commit 6138263837a802d9b32c9a5a5daf668378384108 as bad when it should have been good:

git bisect log > /tmp/bisect.log

The log will look something like this:

git bisect start
# good: [f2fd95cc92fa63a8a1a38a2ff2a8ccd406286849] Add handling for shapes we previously considered non-primitive.
git bisect good f2fd95cc92fa63a8a1a38a2ff2a8ccd406286849
# good: [3f4b51f80ac276e471809ed6127b0d893df01875] Re-enable texture filling of arbitrary polygons.
git bisect good 3f4b51f80ac276e471809ed6127b0d893df01875
# bad: [0b72a4ac45df7b483b61a1799557ac952b74b398] Add the ability to rotate the camera 35 degrees off of the normal.
git bisect bad 0b72a4ac45df7b483b61a1799557ac952b74b398
# bad: [7aca2e12f0e76b73a408d4d13aad52d7af1f4a84] Merge branch 'jwir3/#961-ear-clipping'
git bisect bad 7aca2e12f0e76b73a408d4d13aad52d7af1f4a84
# bad: [a73eed9a145bea5c05833f33eb26eec6] Subdivide all polygons into triangles using ear-clipping algorithm.
git bisect bad a73eed9a145bea5c05833f33eb26eec6
# bad: [6138263837a802d9b32c9a5a5daf668378384108] Add package for more general matrix math computations.
git bisect bad 6138263837a802d9b32c9a5a5daf668378384108

Remove these last two lines (or, alternatively, change the last line to git bisect good 6138263837a802d9b32c9a5a5daf668378384108, save the file, and then run git bisect replay:

scottj|(6138263...) *|BISECTING:~/Source/SinkingMoon/website$ git bisect reset
Previous HEAD position was 6138263... Add package for more general matrix math computations.
Switched to branch 'master'
scottj|master:~/Source/SinkingMoon/website$ git bisect replay /tmp/bisect.log
We are not bisecting.
Bisecting: a merge base must be tested
[6138263837a802d9b32c9a5a5daf668378384108] Subdivide all polygons into triangles using ear-clipping algorithm.
scottj|(6138263...) *|BISECTING:~/Source/SinkingMoon/website$

Automating Git Bisect

There is one other feature of git bisect I find useful from time to time: the ability to automate the testing process, namely git bisect run ^[9]:

git bisect run /tmp/script.sh [optional arguments to the script]

Of course, you need to write this script, but it is useful if you can automate the testing process. In other words, if the regression is that the source code won't compile, the unit tests don't pass, or some other thing that's easily determinable by a script, you can have this script do the thing in question, and then return with an exit code of 0 if the test passed (i.e. no regression was present in this revision) or any number in the range 1-127, excluding 125, if the test failed (i.e. the regression was present in this revision). The special value 125 is only returned if the test can't be run (i.e. the equivalent of git bisect skip).

Conclusion

git bisect is a tool that you can use to track down regressions in your code. Remember:

git bisect will delve into commits made on separate branches and subsequently merged, provided the merge commits aren’t squashed into a single commit.
git bisect only works at the commit level, so it’s more effective if you have smaller, bite-sized commits.
git bisect can be used to find anything that was introduced in a specific commit - it doesn’t have to be a regression. You can use it to find, for example, the first time a feature was introduced.
Even though git bisect can be used for many things (see aforementioned comment), it’s better to use some other method of tracking/searching (e.g. recording the features in every release using git tag), if possible, as it’s likely faster than a manual binary search.
While you can use git bisect skip to skip a commit that can't be tested, it's better to avoid this as it can add ambiguity to your results. (As a corollary, try to only commit things that don’t have general, glaring errors and that compile and run at the most basic level).

You can learn more about git bisect (it has many other cool things, like the ability to change the terms for a bisect session from "good" and "bad" to anything you want - like present and missing, for feature determination) from the git bisect documentation page. It's actually very readable documentation, and I highly recommend giving it at least a cursory glance.

My biggest recommendation in learning how to use git bisect effectively, though, is to do it. When you've identified a problem that you think can be solved with git bisect, try to solve it using that tool! This will teach you much about the tool. If you have any questions, I'm always open to answering them in the comments below, on slack/IRC as jwir3, or via email at jaywir3@gmail.com.

References and Notes

A Binary Search is a special type of search which divides the search space in half, checks one half of it, then recurses on one of the two halves, depending on the outcome of the initial check. ↩︎
See my other post, Rebasing Toward Independence for advice on how to make sure your repository satisfies these rules. ↩︎
Geelnard, Marcus. (2015). A tidy, linear git history. Retrieved 30 January 2018 from http://www.bitsnbites.eu/a-tidy-linear-git-history/. ↩︎
If you want to look to see if your git history is linear, try using the command git log --graph --oneline --abbrev=6. This will show you a graph of your git commits, and you can look to see if it's a linear graph (looks like the first image) or a non-linear graph (looks like the second image). ↩︎
You should, of course, try to minimize the number of steps in the bisect process, so if you know that a commit earlier than HEAD is bad, use that one instead, as it will save you time in the bisect process. That said, it's a trade-off between this and manually attempting to find a commit closer to the actual regression, because the closer you get to the regression, the more time git bisect will spend on the other side of the binary search. Thus, about 85%-90% of the time, I just use HEAD as my "known bad" commit. ↩︎
I'm using git-prompt with zsh on Mac OSX for all of the following examples, which is why you'll see the steps remaining when I run git rebase. Your mileage may vary if you're using a different shell or OS. ↩︎
Often, this happens because of a compile-time error that was added as a non-final commit in a branch prior to merging. This is annoying, because, unless you can fix it trivially and without biasing the binary search (i.e. accidentally fixing the regression or making it worse), you won't be able to do anything with this commit other than skip it. This is part of the reason why each commit should be independently compileable and runnable for each commit, not just for the last commit on a branch (unless you're using squash merges). See also note 2, above. ↩︎
Depending on the length of the diff, you might be able to see the problem immediately. This is more likely if you have small, independent, and straightforward commits. I tend to abide by the phrase "Commit early and often". This is also the reason I don't use squash merges, since they combine a bunch of small commits into a single, monolithic commit, and you lose all of this incremental work (and the ability to find the regression in this incremental work). ↩︎
Git Documentation: Bisect Run. Retrieved 30 Jan 2018 from https://git-scm.com/docs/git-bisect#_bisect_run. ↩︎

Rebasing Toward Independence

Scott Johnson — Thu, 08 Sep 2016 21:09:12 +0000

Introduction

One of the things I will usually do when reviewing code is to verify that every commit within a pull request at least compiles. Since I learned a lot of my craft from developing and reviewing patches, rather than pull requests, this typically was innate in the structure of the code review. Nowadays, though, it's entirely possible that, while a given branch compiles after being merged into another branch, not every commit compiles independently.

You might ask why I'm such a stickler on this. The answer is twofold.

First, I think that commits should be independent of one another. This helps in a number of ways, but mostly it's about the way I think. I want to separate my changes into pieces that are independent of one another, because then I can better summarize them in my mind. This helps me think through, in detail, what steps are required before beginning a particular task. In turn, I've found this leads to less errors and more thought up front, before starting code development.

Second, I use git bisect very often when trying to diagnose a bug that's been found. Bisecting revisions to find where a change occurred is more useful when the commits you're bisecting are small, unrelated, and can be independently compiled. This last part is crucial, because if a specific commit can't be built without adding on other commits, it means you're going to have to git bisect --skip on that commit if it's a pivot point in the bisection search. This increases the likelihood that you're going to end up with multiple commits that could have introduced the bug.

Methodology

Now that I've expounded on the rationale for why you want your commits to be able to be independently compiled, how does one check that this is actually the case? The answer is git rebase.

You're probably thinking "yeah, I don't touch rebase because it changes the git history." That's a good rule of thumb to have for shared branches (e.g. master or develop), but for temporary branches^[1], it's perfectly acceptable to change the history in order to make your commits have a better structure before merging them into your main trunk.

Rebasing Interactively

Git rebase has an interactive switch, -i, that allows you to specify which commits you want to operate on, and what you want to do to them. You just need to specify a starting point (usually your current HEAD) and an ending point:

git checkout feature/my-cool-feature
git rebase -i HEAD~2

This will bring up an editor where you can interactively tell git which commit(s) you want to edit:

In order to edit specific commits, simple change the word pick at the beginning of each line to edit. Then, save the file and exist the editor. Git will now start stepping through the commits, one by one, until it gets to the end of the set of commits you told it to edit. At each step, you simply have to determine if the code compiles. If it does, then you can run git rebase --continue to move on to the next commit.

Iterating Through Commits

The following is an example of how you can step through a branch with a large number of commits to determine, manually, if each commit compiles.

Note : I'm using git-prompt with zsh on Mac OSX for all of the following examples, which is why you'll see the steps remaining when I run git rebase. Your mileage may vary if you're using a different shell or OS.

Check out the branch

git checkout feature/super-cool-feature

Determine how many commits this branch has diverged from the trunk^[2]

git cherry --abbrev=6 -v <trunk-branch> | wc -l

Start git rebase

# Use the commits from the above step in place of XX
git rebase -i HEAD~XX

# You will need to use your editor to make
# all the commit messages start with 'edit'
# instead of 'pick'

Check each commit

# Run your compile command. If it's successful, run:
git rebase --continue

Repeat until finished

Automating It

The above example is fine, and, for most small branches, I'll just do it manually. However, once you have more than ~10 commits, it becomes tiresome. Especially if you've just rebased from master, there were no conflicts, and now you just want to check to make sure everything still compiles, even though you're pretty sure it will.

Here's a small shell script that will enable you to do this automatically:

Fixing a Bad Commit

If you encounter a commit that doesn't compile, you can fix the code to make it compile before running git rebase --continue again. If you're using the above script, it will automatically stop for you if the compilation failed so you can fix it. Once fixed, you can re-run the script to continue.

Conclusion

Now that you know how to quickly check to determine if commits on a branch compile independently and b) how to fix commits that don't compile, I hope you'll use this knowledge to make your commits better. You can also check branches when reviewing code to verify that each commit compiles.

Be diligent about having a hygienic repository! It will save you tons of time in the long run.

Almost all of my projects use a variation of git-flow. If you've never heard of it, I highly recommend checking it out. ↩︎
This command makes use of git cherry, a command I have found extremely useful in the past. You can use it to determine which commits are in one branch but not another. For example, if you wanted to find which commits are in branch my-cool-feature but haven't yet been merged to develop, you could use: git checkout my-cool-feature && git cherry --abbrev=6 -v develop ↩︎

DEV Community: Scott Johnson

How I Write a Commit Message

Introduction

The Rules

Choose a gitmoji to represent your commit

Add a simple subject

Write a body message

Add all metadata at the end of the commit message

A Config to Help You

How can I get my organization to do this?

Rust and Wasm Side-by-Side

Background

The Problem

Possible Solutions[3]

Final Solution

Bonus: Run tests on Travis and deploy WASM to NPM

git bisect: A Gentle Introduction

Motivation

git bisect

Prerequisites

The bisect process

Basics

Starting a Bisect

Marking a Commit

Resetting a Bad Bisect

Automating Git Bisect

Conclusion

References and Notes

Rebasing Toward Independence

Introduction

Methodology

Rebasing Interactively

Iterating Through Commits

Automating It

Fixing a Bad Commit

Conclusion

Possible Solutions^[3]