DEFINITELY say what you are doing. And then say why.
This blog post is a good description of the most prevalent convention in how to write good and useful messages (e.g. this is what the Linux Kernel does and given the history of git there's some flow down): https://cbea.ms/git-commit/
The key thing that means you should start with what is having a short one-line summary of what you're doing so you can look at a simple log and see which commit you're interested in.
The commit should summarize what IT does, not what YOU did. In ten years, nobody will care who you are or what you did, but they will care what the code does and why.
As a linguistic note, commit messages (at least, English commit messages) almost always use an infinitive verb and therefore may be considered to have no tense at all, though to argue that infinitives have no tense you do need to draw a distinction between tense and aspect.
You're confusing a bare infinitive with an imperative. Infinitives are often, but not always, marked with to. Commit messages are not commands and are not capable of licensing imperative forms.
Here are some examples of bare infinitives in English, with the infinitive form italicized:
1. This organization will help you apply for a loan.
2a. Q: What does he do?
2b. A: Check over the paperwork to be sure everything's right.
A commit message is doing exactly the same thing as occurs in example 2b.
my personal observation: because writing down „what“ is hard. Writing down „why“ is even harder.
The commit message is lazy, but breaking these into separate commits because of some "also" rule of thumb is just blindly following a rule for the sake of it.
Agreed, cargo-culting is always bad!
But, without knowing how OBS development team works, sometimes it does make sense to split commits like this, mainly if you have a larger repository where different people are responsible for different areas in the codebase.
For example, build-scripts sometimes gets managed by other people than the ones writing some core algorithms, who are also different from the people writing public APIs to be consumed by users. In those cases, it makes reviews a lot easier when you can split out to review different commits to different people, instead of having everyone navigate the same commit.
But again, not familiar with the internals nor the development cycle that OBS keeps, so maybe this doesn't make sense in this case.
This commit is based off a branch that was adding support for Apple Silicon.
So the entire PR is not going to look clean until that branch is merged first.
> ...you can't revert just one without reverting the others
That's often true in a split out patchset anyway, so I don't think that on its own it stands as a justification for doing things one way or the other.
Ruthless interactive rebase is one way to fix that last point, but if you take the final result and squash that into a single changeset, there's a point to be made about that as well.
Of course, when merged, it often makes sense to squash some commits together, just like you say - long-term, many of the feature development details are not important.
It's not an either-or proposition.
See also:
https://google.github.io/eng-practices/review/developer/cl-d...
https://microsoft.github.io/code-with-engineering-playbook/c...
My favored github PR template has 3 sections:
- What does this PR do?
- Why is that valuable?
- Link to bug tracker.* Description: (What this does, and why)
* Ref: (Ticket/task link)
* To test: (Specific instructions to make sure things are working as expected)
* To deploy: (What specific servers/services to restart, and operations to perform)
https://github.com/obsproject/obs-studio/pull/5875#issuecomm...
And it looks like they're just going to set the PR to a draft until after 5155 is merged, so it will get cleaned up and be easier to review then:
https://github.com/obsproject/obs-studio/pull/5875#issuecomm...
HN is usually better about sussing out the real story.
This happens with every transition in Apple history. It takes pulling the rug out completely before many devs will do it
Look at the Python transition, the carbon to cocoa transition, even the original Rosetta transition.
Trying to understand the changes and their full implications is nearly impossible. 100 loc is a better top end imho.
https://www.goodreads.com/quotes/214064-if-you-owe-the-bank-...
When people start doing multiple things in a single commit with 1000's of changes, it does become mentally exhausting to review. Unfortunately, it requires either being extremely diligent when making the commits or being familiar with git rebase -i.
Of course, sometimes it's just thousands of lines of new code and impossible to review :).
this is why we have line printers, custom reading tables with balanced soft lighting (print proofing lamps) and more recently, rostrum cameras operated by foot switch.
review with fanfold might be a habit only acquired by formative experience, but once you physically manage the printout, and are comfortably seated with several hundred well spaced lines that aren't directly emitting typically exhausting spikey spectrum light forcing your brain to perform extremely complex colour management to balance your vision, which is the primary factor in concentration depletion in every attempt at testing we've tried over the years, and you mix in modern handwriting recognition and a pico projector display of feedback comments if necessary, I have only witnessed very high productivity. Anyone who is subject to audits will know the satisfaction of dumping fanfold boxes on the auditors desk. Or should.
Also HN: no, not like that!
I don't see how adding an additional capture framework backend would require meaningful changes to the build system.
With some likelihood, in this case, Apple probably won't have the resources to rework their PR and thus the PR will stay un-merged until somebody of the project has time to merge/reimplement the relevant parts.
Which of course is a total shame and I wonder why Apple didn't have "mergeability" in mind when they decided to create their PR. They must have known that "rework the build system" can't be part of a PR adding a capture backend if they wanted any chance of this being merged.
[0] https://github.com/obsproject/obs-studio/pull/5155/commits
Aren't Apple the richest corporation in the World, how would they not have resources; am I missing a joke? Maybe you meant 'will choose not to'?
Before three was Dallas, there was The Rise And Fall Of Reginald Perrin, in the main arc a dark parody of 70s corporate England. If you could find a better audio-visual exposition of the transatlantic difference at the end of the nineteen seventies, you will struggle to find a funnier one.
http://www.leonardrossiter.com/reginaldperrin/CJisms.html
https://www.google.co.uk/search?q=reggie+perrin+i+didn%27t+g...
1. The reviewer
2. Someone scanning commit logs for patches of interest
3. Archaeologists
Archaeologists are people a year, five years, 10 years down the road who are trying to figure out how the code got to be the way that it is, so they can feel confident changing it. (See also "Chesterton's Fence"[1].) Those people should not have to dig out the conversation from some random PR to figure out what's going on.
Not knowing to look to an associated PR thread for a commit would be the equivalent of modern day archaeologists not knowing what "carbon dating" was.
Don’t say what you were doing, say what the commit does. A good commit message completes the sentence “when merged this will …”.
Adding a more detailed description on the second line including why things were done is also not bad, but I have a strong opinion that design notes do not belong in the commit log but in code comments or markdown files that are in the repo, so that they can be found more easily and updated.
The subject describes what is being affected (think easily greppable keywords)
Then, then body should go into detail about the contents and rationale for the changes.
Use specific terms like “add” or “remove” and avoid subjective descriptions like “prepare” “clean” and “fix”
For example this patch says:
> Clean up consistency of tabs/spaces in include_directories.
Well, what does clean up tabs/spaces actually mean? Saying “remove tabs in favor of spaces” is much clearer.
https://github.com/obsproject/obs-studio/pull/5875/commits/8...
provides an excellent example of why commit messages matter. This is more than 1000 lines diff to the build system (and thus potentially very dangerous because of possible supply chain attacks) which has the commit message of
"CI: Update build scripts and Github actions workflow"
Never say what you ware doing (it's obvious this commit is updating build scripts). Say why you are doing it, especially when your commit feels unrelated or at most very tangentially related to the objective of your PR.