2024-02-17 The log is not the text

> Waiting for the bus. Italian kids on speed doing superhero moves behind my back and the parents are not in control. I am distracting myself by writing up a fediverse thread.

I was talking with @Sandra@idiomdrottning.org, @splitbrain@octodon.social and @phf@social.sdf.org about git logs. I claimed the following:

> Git does not have wiki culture. If I could rebase and squash and edit to my hearts delight, that would work for me. But git has blockchain culture: write once, append only, no take-backs, and I don’t like it.

The reason I say this is because the artefact I’m interested in is the git log as a readable text. When I need to upgrade software such as Mojolicious or GoToSocial, I often look at a release page, but I hardly every look at the details. I don’t care for long lists of issues and I certainly do not read the git log.

My claim is that the git log is useless for the purposes of learning about new features added or migrations to run during upgrades. And my own commit logs are just as useless because I don’t dare edit and squash the history. The git log is simply a comment for the edits made to the code and does not serve as a replacement for release notes, as far as I am concerned.

So, while it is true that the wiki history is not edited either, the wiki text as the readable end-product is in fact edited. The git log and its messages are not.

I guess I’m an undisciplined programmer who is convinced the feature is done and then discovers an edge case, and the I realize I forgot the docs, and then I find a better way to describe it, oh and here is a test that makes sense, oh and I found a typo and here is a grammar fix. It’s hard for me to know when the feature is done-done. There never is a good point where I think to myself: Now is a good point to merge.

This is just like buying and selling stock. It is hard to know what the future brings. All that you can do is try and make sure there are no catastrophic failures when things go wrong.

The Perl code archive (CPAN) suggests a `Changes` file. I think I’ll try that.

​#Programming

@Sandra@idiomdrottning.org left the following comment:

> Git does not have wiki culture. […] But git has blockchain culture

That’s not quite what you started with. I said git has wiki culture. Git makes the entire software world one big wiki. I had just been reflecting on that earlier, finally having fixed* a long standing bug in markdowku. That’s such a marvel to me, that thanks to git I could make a version that works for me and my friends and I could send the fix upstream so they could apply it or not. When I see a typo or error on a webpage, if that webpage is a wiki, I can fix, I can fix! And thanks to git, it makes even more things be like wikis in that regard.

Git is not a linear line of append append append. It’s a flexible bowl of paperclips, malleable, friendly, it helps me, it’s my friend. If upstream doesn’t merge I’m still gonna be OK. I love git. Don’t slag it.

And the log isn’t just linear either: it makes the source repo be like a wiki in that there’s both a global “recent changes” and a local “page history” for each file, even each line with a good blame viewer.

Now, is documentation outside of the log, for migrations for example, a good idea? Yes. We want README and INSTALL and TODO and COPYING, we want docs. Never disputed that.

*: here’s hoping 🤞🏻

---

Sandra is right, of course. The original conversation went something like this:

Alex

I guess I should start writing some sort of release notes with user-visible changes for Oddmu, my wiki/blog/memex/static site generator…

Sandra

Don’t worry we have git log

Alex

all I know is that I never look at git log of other projects

Sandra

git log of other projects is like 99% of my reading

Alex

wow, sounds like IT hell! Or perhaps my own commit log is just so badly written. And the only commits I know are from the office and they are the worst.

Sandra

Git logs are wiki culture

Alex

If I could rebase and squash and edit to my hearts delight, that would work for me. But git has blockchain culture, write once, append only, no take-backs, and I don’t like it. So effectively I’d like a user-facing Changes file.

Sandra

Like I do 💁🏻‍♀️ Living the dream

Alex

daaaang, is this git envy I feel‽ 😄