Part Two, Git Recommendations Revisited. (Part One is Here)
Since we’re talking code, we should come to grips with the ungainly topic of version control itself before going much further, which in 2020 still means git. On this site (~6 years ago! with not the most generous title) we went over what could be considered a common-enough basic workflow and tips for git beginners, this time around I’m going to point out a more team-focused workflow and newer developments or caveats about that post:
Originally I encouraged forking into your user’s namespace/account instead of potentially piling up branches, or having to be explicitly added to the destination repo so you can create them there. This helped folks who often forgot to click the box to delete their short-lived branches on merge, which the web tools can even clean up in the (remote) forked space for you. I recommended this guidance as good hygiene, but there’s one caveat: automated testing/CI/CD runners may only be available on the main repo/project, so if it’s configured that way then sending a pull/merge request could trigger tests to be run on the remote/’userspace’ repo, and it could complain/not work. If the runner can’t be configured for individual users it’s no big deal to branch ‘locally’ to the repo, especially if common ‘guard rails’ like approvals/protected branches are in place. If you haven’t run into that as an issue, the overarching guidance remains. (Or if it’s too obscure to understand what I’m warning against, like, y’know, git is weird, please follow up with us in the comments or on the Twitters.)
One of the first times I really started to hate git’s user experience was squashing commits or trying to not include updates/’catch up’ commits in a fork/branch in my user account/space. You lose no ‘internet cool’ points if you delete your fork entirely in the web GUI and start over wherever the main branch you’d previously forking off of is at now, but there’s also this post about catching up your fork in a way that people have had success with.
If your team tracks work in a bug tracking/ticketing system, it may provide good context and extra metadata (or just be convention) to prefix your branch names and/or commit messages with the related identifier. (Some Jira-specific integrations I’ve seen actually rely on it and can provide context/feed metrics.) No, the code is not the documentation, unlike my obscure elusive magical unicorn comments, even the most verbose/perfectly-written comments are probably not enough context… This is just to say when an out-of-band communication method is preferred for a project, please consider using it. Wiki’s similarly exist for a reason.
Quick Tangent
Definitely don’t be like me and call ‘everything my beginners mind gets tripped up on’ a ‘frequently asked question’, although these getting started questions could use recording somewhere in my opinion. Imagine someone new to your team, new to the language, the framework, new to coding/version control, and help them in a discoverable way like you would have appreciated!
While we’re talking docs, something that previous teams I worked with in sysadminery aspired to, (at least take the time to think about actually doing eventually) is straight up test plans – formal documentation on how to exercise the code, how to pull together the moving parts or get access to applicable test data/accounts/systems. If it’s a trickier deployment, what’s the (set of) success metric(s), rollback steps to follow, etc. This may actually be coupled with the idea that your design document (something else we’ll cover in a subsequent post) led to these decisions. Side benefit, it can become a preview of potential maintenance tasks to support a measurable service-level objective. If we want to get buzz-wordy. (I promise, no story points or other stuff I haven’t actually been required to show ‘agility’ with! Got a reason why scrummy work is helpful/horrible? Holler at us on the Twitters or in the comments!)
Back to the-actual-name-is-Linus’s-Monster, there’s all sorts of opinions on styles and conventions you could use for the commits themselves, and the first reference I recall coming across was this one. The gist is, code diffs already explicitly say what changed, so you’re encouraged to think about it from a workflow perspective: the specifics are less important than why it changed over time: imagine scanning the commit history to notice when a ‘shift’ occurred, when intent or functionality shifted. Issue tracker/ticket notes and the full body/description of a commit are where you can provide additional context. Git was designed to use email as its primary communication method, all of this back-and-forth should be considered written communication and approached accordingly. Or maybe you don’t want to think about it too much, all of this is to say record more of what you were trying to achieve (to use a Neagle-ism), less of how you mechanically did it. (Typo commits can get rolled up and squashed anyway.)
Another less commonly discussed topic is how often to commit, what or how often to squash, and I guess we can relate it to why we’re putting this under ‘revision control’ in the first place. Just like why you backup your files – it’s for the restore, right? Only your team knows how much value seeing the code’s evolution over time actually has, keep in mind tags and ‘topic’ branches that you use while working on a specific release/feature/issue may provide a good-enough record of signposts in time that will still be around in retrievable history, even if every iteration isn’t in the primary branch those events are formulated in. This is all to say I personally tend to not see value in making granular commits e.g. per file changed, nor does every commit from the topic branch require preserving when merging; I often squash in the GUI and not worry what iterations were involved. It’s almost as if the mainline history should consist only of merge ‘events’ and the state of commits in branches don’t matter until after it gets eyes on/potentially altered in a review. (‘Draft’/WIP/Work In Progress designations are similarly used to conserve on commits that need to get merged with a topic branch into the ‘main’ branch.)
Maybe you don’t need to gpg/pgp-sign commits (via @groob). Maybe you work in ‘security’ and want to show you’re tall enough to ride/can attest to managing some extra sort of complication for benefits you perceive as important. I’m basically doing it for the ‘gram internet cool points fo sho, via a system/app that may already be abandonware (like GPGTools tends to look like at times with slower new-OS-release adoption).
In web GUIs/systems like Gitlab and GitHub, committing tweaks to the branch you sent a pull/merge request from will automagically update the changelist/merge/pull request accordingly. Just in case that’s news to some. Also specific to those webapps, reviewers can make code change suggestions to be accepted/applied by the author right there in the web interface while commenting on lines/reviewing, which is often ideal – it’s certainly more collaborative, since the reviewer can spell out exactly how they expect requested changes to be implemented.
In our next post we’ll get into semi language-agnostic style generalities, stay tuned!
Got other hot gossgit tips/code review thoughts? Use your tweet horn to holler at me!
Allister Banks
Allister lives in Japan, has not read the Slack scroll back, and therefore has no idea what is going on.
Follow Me:
by 
Recent Comments