Ben's Website

Serious musings

Gitting Long In The Tooth

gitdevelopmentopinion
Obligatory XKCD 1597

Git's dueling roles

Many are aware of git's tedious CLI, complex footguns, and other warts, but as a mostly-solo dev, what most annoys me is its orientation to code review rather than writing.

There are typically two kinds of git users: contributors and reviewers. Contributors figure out things and implement them, while reviewers check that the contributions will merge nicely into the rest of the codebase, having their intended effect while not breaking other things. While these roles can be performed by the same person, viewing them separately shows that git's UI is strongly oriented to the latter.

This is most clearly seen in branching and committing, where branches get a terse name while it is good practice to make a lengthier commit message describing all of the work done. The problem is that terseness when opening a new branch can leave that branch without a clear goal. Obviously there is a strong element of developer maturity, process, and rigor here that should supply for any absence or weakness of a tool, but I think its fair to call attention to these two roles and to desire that an essential tool like git, or its successor, correctly models how it is used.

After git

So, how would I like to work with Git or its successor? A starting point is to "Always know what the next thing to do is" and this leads easily the small, edible task detailing advocated in Basecamp's Shape Up.

Suppose I cannot schedule my time and can only expect small increments; how can I get any work done? Similarly, what if my organization like really believes in fungible tasks, that all work is interchangeable, requiring as little specialization as possible. These extremes suggest a highly atomic workflow, where tasks are progressively broken into smaller and smaller chunks in an applied shaping process.

What tools may enable productive work in this manner? This scenario quickly shows that narrating around the work is as essential as actually, eventually, doing the particular task. Whereas other workflows skip this narration and leave it inside the developer's head, here it must be written out because the developer is so limited. Clearly needs guidelines to ensure the narration actually communicates the necessary context on down the chain. AI may be able to assist this elucidation.

Focusing in, my real question here is how can git support this microtask workflow? It might look like this: At the start of the day you sit down to git and review the existing branches in some project. Under a branch title, the first commit is of a shaping brief, describing the task and its connection to the rest of the project. (This branch was created from some other branch by the creation of this shaping document.)

Now, checking the branch out transports you to some prior state of the project, one reflecting the environment the brief was written in. While reading the brief, the first question is whether the context is still accurate and whether it can be updated to the current project state. That is, the minimal work is not to score but to merely move the chains, to update the brief to the current project status as much as can be known. If the context has changed in a major way, updating may be inappropriate without greater exploration of the original motivation and objectives. In this case some translation may be needed, likely in a subsequent branch that closes the original.

(Here I'm basically linking branches to GitHub issues, placing the normal issue stuff in the summary document on the branch. This links the place where the work is done, the branch, with the work the work that is done, and the motivation for that work. Instead of treating issues as a separate thing that can be referenced, and that exist outside of the repository, this is entirely within, aided by some git automations.)

Now after the context has been updated to the present project state, that is the work reshaped to present, the work can actually begin, leading to either the implementation as sketched in the brief or a further subdivision into smaller parts and other branches, a breadth-first shaping process.

And that is basically it: work gets done by either doing more design or completing the designed task. Committing the work triggers a standard review, checking first that the commit followed the design brief and works, and second that it actually does integrate with the larger project in the expected way.

Also important is that the initial checkout is a clocked event, locally and on the remote, as are any commits closing the branch and reviews. This provides built-in time and resource tracking.

What comes out of this is, I think, work of higher quality, not because it is technically better but because the work is surrounded by its context, ostensibly improving maintainability and project coherence.

I think the next step here is to define the contemplated workflows and task templates, tbd. Thanks for reading, please send me any comments!