Contextual commits – An open standard for capturing the why in Git history
31–39 of 39 posts
Re: Contextual commits – An open standard for capturing the why in Git history
#32Earlier quoted context omitted.
The problem is that usually we don't write the WHY in the commits... We tend to always capture the WHAT in the form of prose. And for agents, this is just more noise, since all they need is just the diff to reconstruct the WHAT. I've never seen someone write decisions or the intent they started with in commit messages. Even the solutions today that auto-generate commit messages just summarise the diff. This was helpf…
> I've never seen someone write decisions or the intent they started with in commit messages You may not have seen enough good repos. The following is an example commit from freebsd https://cgit.freebsd.org/src/commit/?id=ac5ff2813027c385f903... A proper email is like an email. You have the first line as the subject and it may be enough to explain the intent of the diff. But sometimes it’s not enough and you add more…
> The following is an example commit from freebsd
The Linux kernel is another great example. Random commit from yesterday:
https://github.com/torvalds/linux/commit/d56b5d163458c45ab8f...
Re: Contextual commits – An open standard for capturing the why in Git history
#33> intent(auth): users need social login, starting with Google before GitHub and Apple Your 'intent' is 'users need social login'? That does not make sense. Your intent is 'Getting more users by lowering barriers to sign up', a business goal. That business goal might have hierarchical children – for example, Jira epics – such as 'offer social sign-in', or 'declutter landing page.' Also, the commit mentions 'Google bef…
> Your intent is 'Getting more users by lowering barriers to sign up', a business goal.
Important point.
But it says more about OP’s perspective on product-driven development than this “contextual commits”.
The idea that OP does not follow up on is whether these codified commit messages with a very shallow summary of the LLM context improve anything compared to the normal commit messages that Claude will generate.
I suspect they’re equally insufficient since even a compacted context seems less diffusing and it’s still a lot bigger than these.
> I wish our profession would stop trying to reinvent issue tracking in git every week.
I would love to have good git-powered issue tracking. I haven’t seen it yet.
Re: Contextual commits – An open standard for capturing the why in Git history
#34Earlier quoted context omitted.
The problem is that usually we don't write the WHY in the commits... We tend to always capture the WHAT in the form of prose. And for agents, this is just more noise, since all they need is just the diff to reconstruct the WHAT. I've never seen someone write decisions or the intent they started with in commit messages. Even the solutions today that auto-generate commit messages just summarise the diff. This was helpf…
Because commit history is here to explain WHAT and not WHY. "Why" is explained by a decision log such as ADR which can be store in the same repo and can be mutated in the same commit that has WHAT in its commit body. But also, if you look at large projects like Linux or FreeBSD, commits there explain why as well.
> Because commit history is here to explain WHAT and not WHY.
When that commit gets implicated by `git bisect` and all you see in the message is exactly what you’d see by reading the patch anyway, you’ll wish the author answered why they did what they did. This, especially, when the author is no longer at the company.
Re: Contextual commits – An open standard for capturing the why in Git history
#35Our standard of practice is to document the “why” in Jira. Then reference that card in the commit message. This gives product owners the ability to embellish as they wish and reduces the need of the dev to repeat themselves.
And someday jira is dumped for a different system and tickets slowly become unavailable.
But, perhaps the IDE could retrieve the details of the jira card, and help pre-generate the commit message from it.
If only tickets would be part of the repository itself from the beginning, that would be much simpler IMO.
Re: Contextual commits – An open standard for capturing the why in Git history
#36Earlier quoted context omitted.
The problem is that usually we don't write the WHY in the commits... We tend to always capture the WHAT in the form of prose. And for agents, this is just more noise, since all they need is just the diff to reconstruct the WHAT. I've never seen someone write decisions or the intent they started with in commit messages. Even the solutions today that auto-generate commit messages just summarise the diff. This was helpf…
> I've never seen someone write decisions or the intent they started with in commit messages You may not have seen enough good repos. The following is an example commit from freebsd https://cgit.freebsd.org/src/commit/?id=ac5ff2813027c385f903... A proper email is like an email. You have the first line as the subject and it may be enough to explain the intent of the diff. But sometimes it’s not enough and you add more…
Obviously projects have their own standards around comments, but as the why is apparently important and non-obvious, would it be even better for the ‘why’ to be a code comment in order to understand why code exists without looking through the git history for each line?
Re: Contextual commits – An open standard for capturing the why in Git history
#37Earlier quoted context omitted.
> I've never seen someone write decisions or the intent they started with in commit messages You may not have seen enough good repos. The following is an example commit from freebsd https://cgit.freebsd.org/src/commit/?id=ac5ff2813027c385f903... A proper email is like an email. You have the first line as the subject and it may be enough to explain the intent of the diff. But sometimes it’s not enough and you add more…
This looks very good. Thanks for sharing. I can only imagine how much discipline it takes to write these kinds of commits manually.
You don’t have to look far to find it. Git and Linux, the two first Git-based projects, work like this.
You could have found this if you did just a little research before declaring an open standard.
Re: Contextual commits – An open standard for capturing the why in Git history
#38Earlier quoted context omitted.
The problem is that usually we don't write the WHY in the commits... We tend to always capture the WHAT in the form of prose. And for agents, this is just more noise, since all they need is just the diff to reconstruct the WHAT. I've never seen someone write decisions or the intent they started with in commit messages. Even the solutions today that auto-generate commit messages just summarise the diff. This was helpf…
> I've never seen someone write decisions or the intent they started with in commit messages You may not have seen enough good repos. The following is an example commit from freebsd https://cgit.freebsd.org/src/commit/?id=ac5ff2813027c385f903... A proper email is like an email. You have the first line as the subject and it may be enough to explain the intent of the diff. But sometimes it’s not enough and you add more…
> A proper email is like an email.
A proper commit message is like an email?
Re: Contextual commits – An open standard for capturing the why in Git history
#39It continually amazes me how averse people are to just explaining why a commit exists in the body of the commit. Is all this tagging actually easier to read than written prose? You don’t even have to write it anymore if the sight of your editor opening upon `git commit` causes some instinctual revulsion.
The problem is that usually we don't write the WHY in the commits... We tend to always capture the WHAT in the form of prose. And for agents, this is just more noise, since all they need is just the diff to reconstruct the WHAT. I've never seen someone write decisions or the intent they started with in commit messages. Even the solutions today that auto-generate commit messages just summarise the diff. This was helpf…
The WHY in the commit should just be a ticket ID or reference, at the beginning of the commit.
And IMHO in the first place the code is meant to be for humans, not machines/programs. Rhetorical question : If the LLMs are so great, why don't they just generate bytecode for binaries directly ?