There was this old statue with a large plaque under it bearing his name. I asked my mum who he was, she didn't know.
I understood the point of a statue was to be remembered if not honored for something but they forgot to describe who he was.
Eventually very little will remain to remember us by. You will likely be reduced eventually to a single commit message.
Therefore I coin a micro-format for code comments and commit messages. You should start with a child hood story, then comes a section about what you've learned that day, then you explain how it applies to the code and finally what have you done.
It's not really imperative, it's just commit-message-present. The implicit subject is "I", referring to the patch, like Smalltalk documentation style. This canard goes as high as Junio himself, though. :)
> The former varies in length and form; the latter is concise and consistent.
IMHO, even though the latter is shorter, I did not get why it's that much better. I think in some ways, shorter is not better at all.
I try to follow these rules when writing commit messages, and had wuite good experience with them:
- in the first line, name the changed subsystem/component and then a short description of what changed
- follow with a list of bummet points about key changes and their reasoning, especially if something was renamed/moved/...
- always reference a ticket, a comment of a ticket, or some other reference
If I re-read the commit message, I want to be able to know (or have at least an idea and to know where to look further) _why_ the code is at it is.
Always was puzzled by this "use present/imperative" prescription, to be fair. Shouldn't the messages about the past work be preterite/simple past? "Added support for OpenFizz 3.1", "Fixed FOO-2123 with foos that don't foo", "Changed default shell from /bin/fish to /bin/tcsh", etc. Heck, even the titular xkcd has initial commit messages in the Past Simple.
The way to think about it is you're not describing the work you've done, you're describing what the commit does.
It makes more sense that way if you think about the way in which Git is used for Linux development. They review individual commits so the commit message describes the change that will occur if that commit is pulled. Also commits can have multiple revisions as the change is improved, so past tense isn't correct because it can still change.
There was this old statue with a large plaque under it bearing his name. I asked my mum who he was, she didn't know.
I understood the point of a statue was to be remembered if not honored for something but they forgot to describe who he was.
Eventually very little will remain to remember us by. You will likely be reduced eventually to a single commit message.
Therefore I coin a micro-format for code comments and commit messages. You should start with a child hood story, then comes a section about what you've learned that day, then you explain how it applies to the code and finally what have you done.
It's not really imperative, it's just commit-message-present. The implicit subject is "I", referring to the patch, like Smalltalk documentation style. This canard goes as high as Junio himself, though. :)
> The former varies in length and form; the latter is concise and consistent.
IMHO, even though the latter is shorter, I did not get why it's that much better. I think in some ways, shorter is not better at all.
I try to follow these rules when writing commit messages, and had wuite good experience with them: - in the first line, name the changed subsystem/component and then a short description of what changed - follow with a list of bummet points about key changes and their reasoning, especially if something was renamed/moved/... - always reference a ticket, a comment of a ticket, or some other reference
If I re-read the commit message, I want to be able to know (or have at least an idea and to know where to look further) _why_ the code is at it is.
Always was puzzled by this "use present/imperative" prescription, to be fair. Shouldn't the messages about the past work be preterite/simple past? "Added support for OpenFizz 3.1", "Fixed FOO-2123 with foos that don't foo", "Changed default shell from /bin/fish to /bin/tcsh", etc. Heck, even the titular xkcd has initial commit messages in the Past Simple.
The way to think about it is you're not describing the work you've done, you're describing what the commit does.
It makes more sense that way if you think about the way in which Git is used for Linux development. They review individual commits so the commit message describes the change that will occur if that commit is pulled. Also commits can have multiple revisions as the change is improved, so past tense isn't correct because it can still change.
The "built-in" commit messages (e.g. "Revert ...") are imperative, so if nothing else it's consistent.
The way I read them is as statements of intent, i.e. "[this commit will] Merge/Revert/Add/Fix ...".