diff options
author | Daniel Silverstone <dsilvers@digital-scurf.org> | 2020-05-11 20:31:38 +0100 |
---|---|---|
committer | Daniel Silverstone <dsilvers@digital-scurf.org> | 2020-05-11 20:31:38 +0100 |
commit | d9a59b207c3f8654c556ac03c930d1f60458a8ea (patch) | |
tree | ab902be5c0629872a808fcfac33da7a38196580b | |
parent | c75d3632988e67197f1804d0a9c3c39fd4258e56 (diff) | |
download | blog-d9a59b207c3f8654c556ac03c930d1f60458a8ea.tar.bz2 |
Posting about book club
-rw-r--r-- | posts/bookclub-20200511.mdwn | 147 |
1 files changed, 147 insertions, 0 deletions
diff --git a/posts/bookclub-20200511.mdwn b/posts/bookclub-20200511.mdwn new file mode 100644 index 0000000..15f7e9f --- /dev/null +++ b/posts/bookclub-20200511.mdwn @@ -0,0 +1,147 @@ +[[!meta title="The Lars, Mark, and Daniel Club"]] +[[!meta author="Daniel Silverstone"]] +[[!meta date="2020-05-11 20:00:00"]] +[[!tag draft]] + +Today [Lars][], [Mark][], and I discussed Jeremy Kun's [The communicative value +of using Git well][article] post. While a lot of our discussion was spawned by +the article, we did go off-piste a little, and I hope that my notes below will +enlighten you all as to a bit of how we see revision control these days. It +was remarkably pleasant to read an article where the comments section wasn't a +cesspool of horror, so if this posting encourages you to go and read the +article, don't stop when you reach the bottom -- the comments are good and +useful too. + +[Lars]: https://blog.liw.fi/ +[Mark]: https://blog.sirena.org.uk/ +[article]: https://jeremykun.com/2020/01/14/the-communicative-value-of-using-git-well/ + +*** + +This was a fairly non-contentious article for us though each of us had points +we wished to bring up and chat about it turned into a very convivial chat. +We saw the main thrust of the article as being about using the metadata of +revision control to communicate intent, process, and decision making. We +agreed that it must be possible to do so effectively with Mercurial (thus +deciding that the mention of it was simply a bit of clickbait / red herring) +and indeed Mark figured that he was doing at least some of this kind of thing +way back with CVS. + +We all discussed how knowing the fundamentals of Git's data model improved our +ability to work wih the tool. Lars and I mentioned how jarring it has originally +been to come to Git from revision control systems such as Bazaar (`bzr`) but +how over time we came to appreciate Git for what it is. For Mark this was less +painful because he came to Git early enough that there was little more than the +fundamental data model, without much of the [porcelain][] which now exists. + +[porcelain]: https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain + +One point which we all, though Mark in particular, felt was worth considering +was that of distinguishing between published and unpublished changes. The +article touches on it a little, but one of the benefits of the workflow which +Jeremy espouses is that of using the revision control system as an integral +part of the review pipeline. This is perhaps done very well with Git based +workflows, but can be done with other VCSs. + +With respect to the points Jeremy makes regarding making commits which are good +for reviewing, we had a general agreement that things were good and sensible, +to a point, but that some things were missed out on. For example, I raised +that commit messages often need to be more thorough than one-liners, but +Jeremy's examples (perhaps through expedience for the article?) were all pretty +trite one-liners which perhaps would have been entirely obvious from the commit +content. Jeremy makes the point that large changes are hard to review, and +Lars poined out that [Greg Wilson did research][gwilson] in this area, and at +least one [article][article200] mentions 200 lines as a maximum size of a +reviewable segment. + +[gwilson]: https://arxiv.org/abs/1407.5648 +[article200]: https://uwescience.github.io/neuroinformatics/2017/10/08/code-review.html + +I had a brief warble at this point about how reviewing needs to be able to +consider the whole of the intended change (i.e. a diff from base to tip) not +just individual commits, which is also missing from Jeremy's article, but that +such a review does not need to necessarily be thorough and detailed since the +commit-by-commit review remains necessary. I use that high level diff as a way +to get a feel for the full shape of the intended change, a look at the end-game +if you will, before I read the story of how someone got to it. As an aside at +this point, I talked about how Jeremy included a 'style fixes' commit in his +example, but I **loathe** seeing such things and would much rather it was +either not in the series because it's unrelated to it; or else the style fixes +were folded into the commits they were related to. + +We discussed how style rules, as well as commit-bisectability, and other rules +which may exist for a codebase, the adherence to which would form part of the +checks that a code reviewer may perform, are there to be held to when they +**help** the project, and to be _broken_ when they are in the way of good +communication between humans. + +In this, Lars talked about how revision control histories provide high level +valuable communication _between developers_. Communication between humans is +fraught with error and the rules are not always clear on what will work and +what won't, since this depends on the communicators, the context, etc. However +whatever communication rules are in place should be followed. We often say +that it takes two people to communicate information, but when you're writing +commit messages or arranging your commit history, the second party is often +nebulous "other" and so the code reviewer fulfils that role to concretise it +for the purpose of communication. + +At this point, I wondered a little about what value there might be (if any) in +maintaining the metachanges (pull request info, mailing list discussions, etc) +for historical context of decision making. Mark suggested that this is useful +for design decisions etc but not for the style/correctness discussions which +often form a large section of review feedback. Maybe some of the metachange +tracking is done automatically by the review causing the augmentation of the +changes (e.g. by comments, or inclusion of design documentation changes) to +explain _why_ changes are made. + +We discussed how the "rebase always vs. rebase never" feeling flip-flopped in +us for many years until, as an example, what finally won Lars over was that he +wants the history of the project to tell the story, in the git commits, of how +the software has changed and evolved in an **intentional** manner. Lars said +that he doesn't care about the meanderings, but rather about a clear story +which can be followed and understood. + +I described this as the switch from "the revision history is about what I did +to achieve the goal" to being more "the revision history is how I would hope +someone else would have done this". Mark further refined that to "The revision +history of a project tells the story of how the project, as a whole, _chose_ to +perform its sequence of evolution." + +We discussed how project history must necessarily then contain issue tracking, +mailing list discussions, wikis, etc. There are exist free software projects +where part of their history is forever lost because, for example, the project +moved from Sourceforge to Github, but made no effort (or was unable) to migrate +issues or somesuch. Linkages between changes and the issues they relate to +can easily be broken, though at least with mailing lists you can often rewrite +URLs if you have something consistent like a `Message-Id`. + +We talked about how cover notes, pull request messages, etc. can thus also be +lost to some extent. Is this an argument to always use merges whose message +bodies contain those details, rather than always fast-forwarding? Or is it a +reason to encapsulate all those discussions into git objects which can be +forever associated with the changes in the DAG? + +We then diverted into discussion of CI, testing every commit, and the benefits +and limitations of automated testing vs. manual testing; though I think that's +a little too off-piste for even this summary. We also talked about how commit +message audiences include software perhaps, with the recent movement toward +[conventional commits][ccommits] and how, with respect to commit messages for +machine readability, it can become very complex/tricky to craft good commit +messages once there are multiple disparate audiences. For projects the size of +the Linux kernel this kind of thing would be nearly impossible, but for smaller +projects, perhaps there's value. + +[ccommits]: https://www.conventionalcommits.org/en/v1.0.0/ + +Finally, we all agreed that we liked the quote at the end of the article, and so +I'd like to close out by repeating it for you all... + +[Hal Abelson][habl] famously said: + +> Programs must be written for people to read, and only incidentally for +> machines to execute. + +[habl]: https://en.wikipedia.org/wiki/Hal_Abelson + +Jeremy agrees, as do we, and extends that to the metacommit information as +well. |