Favor Information in Commit Messages over Web Conversations
I use Github, Gitlab, Codeberg, and sr.ht for my git repositories. Most contributions I make are to Github or Gitlab repositories.
When I submit a pull/merge request, my strong preference is to use my commit message(s) to populate the pull/merge request text.
Why the preference? Because the commit message will continue to travel with the code.
Why is it important to me that this travels with the code?
I tend to favor looking first at the code; then annotations (via git annotate or git blame); then working through the history of the file. As a last resort to understand the code, I might go look at the remote repository’s pull request and commit history.
Also, I tend to think in terms of “What if the remote service is not available to me?” After all remote services go away or change.
I have an internet outage? The host moves from one service to another? Someone nukes their repository?
Pull/merge request conversations don’t move with the code; they are bound to the service that provides that functionality. A not-too-subtle form of vendor lock-in.
All of which is to say, I strongly prefer verbose commit messages over initial verbose pull request descriptions.
In most services, if your merge/pull request has one commit, that service will default the pull request text to the commit message.
But what if I have multiple commits for the pull request? I wrote a simple script to generate a pull request message from those commits.
At it’s core, it really is a configured git command. But this one command helps me create a consistent pull request description that is useful and derived from my commit messages.
Code For Building a Pull/Merge Request Message
In my dotzshrc repository I have a script for building a pull request message.
The following incantation (e.g. cat ~/git/dotzshrc/bin/build-pull-request-message) is my use of Org Babel to copy the text of the shell command into my post.
cat ~/git/dotzshrc/bin/build-pull-request-message
And here is the script’s body. Most of it is help text.
The output of the build-pull-request-message is as follows:
## Subject
SHA
Body
The subject is the fist line of the commit; please keep it terse. The SHA is the commit’s identifier. And the body is the remainder of the commit message.
Conclusion
Try to keep information close to where it’s relevant. Inline documentation close to it’s method. Project documentation close to it’s repository. The “why” of the change close to the change.
Top comments (0)