21–30 of 39 posts
Our 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.
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…
Earlier quoted context omitted.
> 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.
> 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.
Rejected: (auth-library) ...
?To that end you will want to provide a validating parser and then start rejecting commits whose messages don’t validate. If your validator has even one or two bugs you’re going to see all goodwill evaporate, and for what? So that you could read:
bug(fix)[8177] Add missing paren
Add missing paren
…
Fixes http://bugs.com/8177
Our 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.
That’s cool. But how does it work in agentic environment? Do you get any benefit from it? Or it’s intended only for humans to read?
Giving agent scoped access to ticket system. Whis is this obvious answer not the obvious solution?
Would be curious to know if it works better than writing the Why as human-friendly paragraphs in the body of the commit message.
A few examples are the ability to query historical data and using each action line as a signal for other tooling to build on top but there are many others… you can check what Conventional Commits did in the past and what they unlocked only by introducing structure to commit subjects
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…
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.
Anyone who wants their commit titles to be less like document headings and more like parseable data structures is going to find it difficult when their peers don’t play along. To that end you will want to provide a validating parser and then start rejecting commits whose messages don’t validate. If your validator has even one or two bugs you’re going to see all goodwill evaporate, and for what? So that you could read…
It was enraging - I'm trying to provide references to explain the motivation of my changes, all my prose is nicely formated, but the bulleted list of references I've provided is rejecting my commit.
I generally think it's in the category of a social problem not a technical problem - communicate the expectations but don't dogmatically enforce them
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 format is optimised for agent querying and human readability in `git log`, not for `git interpret-trailers` compatibility. Those are different use cases.
> The format is optimised for agent querying and human readability
Yours is key value pairs. Trailers are key value pairs. The git log can be read by humans and agents... what’s even the differentiator here?
Agents read English. But every little minutia of programming now needs something “for agents and humans”? Which is like colon-separated key value pairs... except they also have a scope in parens. Which makes all the difference to agents? tuts