Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Contextual commits – An open standard for capturing the why in Git history

vidimitrov.substack.com

Post reply on HN
Print view View original

11–20 of 39 posts

Re: Contextual commits – An open standard for capturing the why in Git history

#11

Post by vidimitrov »

skydhash wrote: post #9
vidimitrov wrote: post #6

Earlier 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…

This looks very good. Thanks for sharing. I can only imagine how much discipline it takes to write these kinds of commits manually.

Re: Contextual commits – An open standard for capturing the why in Git history

#12

Post by skydhash »

vidimitrov wrote: post #7
keybored wrote: post #5

> an open standard for capturing the WHY in git history Agentic coding keeps reinventing coding. That was my first thought. > And then it hit me - the commit body has always been there. Completely underutilised. Wait. What? This is the standard? > Here is an example of how a Contextual Commit looks: The format is key-value stuff. You can already use trailers for that. The syntax here doesn’t work with that stuff. If…

Trailers were not suitable for the use case. The scope in parentheses is doing real work. `rejected(oauth-library)` lets you do `git log --grep="rejected(auth"` to find every rejected auth decision across history. If you flatten it to a trailer token you either lose the scope or encode it awkwardly as `Rejected-auth-oauth-library: value`, which doesn't grep cleanly and doesn't parse naturally.

I think those are better suited to an issue tracker. As for changes that affected the source code, you can grep the patch in the git log too.

Re: Contextual commits – An open standard for capturing the why in Git history

#13

Post by 0x457 »

vidimitrov wrote: post #6
teeray wrote: post #2

It 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…

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.

Re: Contextual commits – An open standard for capturing the why in Git history

#14

Post by vidimitrov »

skydhash wrote: post #12
vidimitrov wrote: post #7

Earlier quoted context omitted.

Trailers were not suitable for the use case. The scope in parentheses is doing real work. `rejected(oauth-library)` lets you do `git log --grep="rejected(auth"` to find every rejected auth decision across history. If you flatten it to a trailer token you either lose the scope or encode it awkwardly as `Rejected-auth-oauth-library: value`, which doesn't grep cleanly and doesn't parse naturally.

I think those are better suited to an issue tracker. As for changes that affected the source code, you can grep the patch in the git log too.

Issue trackers are full of intent and decisions, that's true, but that's not the point here... It's about a storage that agents can use natively without the need of callings external APIs or MCPs.

And there is a slight difference between what you capture in issue trackers and what happens in reality in coding sessions.

Re: Contextual commits – An open standard for capturing the why in Git history

#15

Post by svstoyanovv »

stephbook wrote: post #10

> 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…

I understood the example, and it could be a minor hiccup there, but the essence is different:

By having a structured context of the key session discoveries, decisions, rejected items (if there were past commits with decisions that had been rejected, etc..) you achieve a type of contextual storage of the reason, thus after a month, when a team member wants to start working on a task that you have touched, and now forgot since you are doing ai-assisted coding and pr throughput is to sky right now, your collegue at least will know the rational behind the decission and working with his agent, the agent will produce more reliable code not introducing something for the sake of solving the task.

Re: Contextual commits – An open standard for capturing the why in Git history

#16

Post by skydhash »

vidimitrov wrote: post #11
skydhash wrote: post #9

Earlier 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.

Is it discipline?

When you think of the patch as an unit of idea and the commit as the means to convey that idea, it takes the same amount of effort to write an email message.

BTW you do not have to write those for every single commit. You can always rebase interactively and create a final set of commits for sharing. No one cares about what’s in your local copy of the repo.

Re: Contextual commits – An open standard for capturing the why in Git history

#17

Post by 0x457 »

vidimitrov wrote: post #7
keybored wrote: post #5

> an open standard for capturing the WHY in git history Agentic coding keeps reinventing coding. That was my first thought. > And then it hit me - the commit body has always been there. Completely underutilised. Wait. What? This is the standard? > Here is an example of how a Contextual Commit looks: The format is key-value stuff. You can already use trailers for that. The syntax here doesn’t work with that stuff. If…

Trailers were not suitable for the use case. The scope in parentheses is doing real work. `rejected(oauth-library)` lets you do `git log --grep="rejected(auth"` to find every rejected auth decision across history. If you flatten it to a trailer token you either lose the scope or encode it awkwardly as `Rejected-auth-oauth-library: value`, which doesn't grep cleanly and doesn't parse naturally.

> The scope in parentheses is doing real work. `rejected(oauth-library)` lets you do `git log --grep="rejected(auth"` to find every rejected auth decision across history.

I'm 99% sure that grep won't find your commit because you rejected "oauth-library" and grepping for "auth" rejection. Given that LLM will make up category name, it will just get worse unless there is deterministic enforcement.

All of this really feels like people that never wrote code starting doing it via agents and started reinventing already solved issues.

Re: Contextual commits – An open standard for capturing the why in Git history

#18

Post by evolve2k »

I like these conventions. Another personal practice I us the body for is where I’ve relied on any webpages; blogs, issue reports, stack overlap pages etc to help the commit come together.

The example of using one library over another, especially if research has gone into which to choose, regularly involves say finding a good article that compares the alternatives.

I’ll say though that I usually include links to more notable references, I won’t usually commit refs to a libraries own docs and more obvious stuff; revealing and keeping references to resources found that went towards getting it done are what I keep and add to commit body.

Maybe there’s spaces for useful references to be added to the spec/conventions. Personally I usually show links like this after the body message.

Example of the commit body:

refs(oath-library):

www.something.com/picking-a-thing

Re: Contextual commits – An open standard for capturing the why in Git history

#20

Post by vidimitrov »

0x457 wrote: post #17
vidimitrov wrote: post #7

Earlier quoted context omitted.

Trailers were not suitable for the use case. The scope in parentheses is doing real work. `rejected(oauth-library)` lets you do `git log --grep="rejected(auth"` to find every rejected auth decision across history. If you flatten it to a trailer token you either lose the scope or encode it awkwardly as `Rejected-auth-oauth-library: value`, which doesn't grep cleanly and doesn't parse naturally.

> The scope in parentheses is doing real work. `rejected(oauth-library)` lets you do `git log --grep="rejected(auth"` to find every rejected auth decision across history. I'm 99% sure that grep won't find your commit because you rejected "oauth-library" and grepping for "auth" rejection. Given that LLM will make up category name, it will just get worse unless there is deterministic enforcement. All of this really fee…

The “deterministic enforcement” is exactly what this enables but its not the responsibility of the spec to say that. Its harnesses or IDEs or you own implementation that will enforce that.
Post reply on HN