Comment by ImPostingOnHN
2 months ago
That sounds like design discussions best had in the issue/ticket itself, before you even start writing code. Then the commit message references the ticket and has a brief summary of the changes.
Writing and reading paragraphs of design discussion in a commit message is not something that seems common.
Ticket systems are quite ephemeral. I still have access to commit messages from the 90s (and I didn't work on the software at the time). I haven't been able to track the contents of the gnats bug tracker from those days.
And of course tickets can be private, so even if the data survived migration, you may not have access to it (principle of least privilege and all that).
if you've changed a function and are worried about the reason for the change not being tracked or disappearing, then add it as a comment, the commit message is not the place for this.
Not really about design, but technical reasons why this solution came to be when it’s not that obvious. It’s not often needed. And when it does, it usually fits in a short paragraph.
> technical reasons why this solution came to be
What you're describing here is a design. The most important parts of a design are the decisions and their reasoning.
e.g. "we decided on tool/library pattern X over tool/library/pattern Y because Z" – that is a design, usually discussed outside (and before) a commit message.
You discuss these decisions with others, document the discussion and decision, and then you have a design and can start writing code.
Let me ask you this: suppose you have a task that needs to be done eventually, and you want to write down some ideas for it, but don't want to start coding right now. Where do you put those ideas? How do you link them to that specific task?
So you'd disagree with style that Linux uses for their commits?
Random example:
Provide a new syscall which has the only purpose to yield the CPU after the kernel granted a time slice extension.
sched_yield() is not suitable for that because it unconditionally schedules, but the end of the time slice extension is not required to schedule when the task was already preempted. This also allows to have a strict check for termination to catch user space invoking random syscalls including sched_yield() from a time slice extension region.
From 99d2592023e5d0a31f5f5a83c694df48239a1e6c
4 replies →
Here is an example
https://cgit.freebsd.org/src/commit/?id=407b1e4980189252fade...
You can find more example there
https://cgit.freebsd.org/src/log/?showmsg=1