News for hackers. Stuff that matters.
Re:Apple contributes to OBS to support screen capture using ... by pilif on Friday January 28, 2022 @05:19AM (#30112830)
This commit in the PR

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.

Re:Apple contributes to OBS to support screen capture using ... by rkangel on Friday January 28, 2022 @05:29AM (#30112894)
> Never say what you ware doing (it's obvious this commit is updating build scripts)

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.

Re:Apple contributes to OBS to support screen capture using ... by Cthulhu_ on Friday January 28, 2022 @08:08AM (#30114098)
Small nit: Maybe not say what YOU are doing, but what the COMMIT, when applied, will do. Git is not a personal work log, it's a source code change log. A commit may be a collaborative effort; it may be a squash of a thousand smaller commits; it may be a merge, it may be generated by a tool (like the dependencies), etc.

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.

Re:Apple contributes to OBS to support screen capture using ... by MrGilbert on Friday January 28, 2022 @08:56AM (#30114580)
That's the main reason we are using present tense in commit messages, not past tense. It's the commit that is applying the changes at that moment.
Re:Apple contributes to OBS to support screen capture using ... by thaumasiotes on Friday January 28, 2022 @04:05PM (#30120357)
> That's the main reason we are using present tense in commit messages, not past tense.

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.

Re:Apple contributes to OBS to support screen capture using ... by timmb on Saturday January 29, 2022 @05:32AM (#30125302)
I believe it’s the imperative (enable widget) not the infinitive (to enable widget) that is generally used.
Re:Apple contributes to OBS to support screen capture using ... by thaumasiotes on Saturday January 29, 2022 @05:17PM (#30131134)
> I believe it’s the imperative (enable widget) not the infinitive (to enable widget)

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.

Re:Apple contributes to OBS to support screen capture using ... by zestyping on Friday January 28, 2022 @01:25PM (#30118461)
Ironically, the referenced article on how to write good git commit messages (https://cbea.ms/git-commit/) gives no "why" for most of its points. It lists 7 rules, of which 2, 3, 4, 5, 6 are simply declared without rationale.
Re:Apple contributes to OBS to support screen capture using ... by pixiemaster on Friday January 28, 2022 @03:29PM (#30119916)
so true.

my personal observation: because writing down „what“ is hard. Writing down „why“ is even harder.

Re:Apple contributes to OBS to support screen capture using ... by pferde on Friday January 28, 2022 @05:52AM (#30113053)
Also, if your commit message has parts that say "also, this", "also, that", don't be lazy and break those alsos into separate commits!
Re:Apple contributes to OBS to support screen capture using ... by jacobmischka on Friday January 28, 2022 @07:01AM (#30113586)
Not necessarily. It sounds like all of the things mentioned in the commit message are interconnected (updating build scripts and updating gitignore to remove the new build directories). It would be pointless to break these into separate commits, you can't revert just one without reverting the others.

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.

Re:Apple contributes to OBS to support screen capture using ... by capableweb on Friday January 28, 2022 @07:12AM (#30113647)
> 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.

Re:Apple contributes to OBS to support screen capture using ... by threeseed on Friday January 28, 2022 @07:18AM (#30113692)
As others have mentioned many times here.

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.

Re:Apple contributes to OBS to support screen capture using ... by capableweb on Friday January 28, 2022 @07:23AM (#30113720)
Yes, makes a lot of sense. Sorry if I gave the impression that I think somehow this PR is wrong or similar. I was just replying to the fact that sometimes splitting up commits makes sense, outside of this PR.
Re:Apple contributes to OBS to support screen capture using ... by rlpb on Friday January 28, 2022 @08:23AM (#30114226)
My exception to the "also" rule of thumb is that if the split changes would cover separate areas of the code such that each piece could be easily picked out by "git add -p", then splitting them out isn't required as long as they are all associated to one logical larger story.

> ...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.

Re:Apple contributes to OBS to support screen capture using ... by Cthulhu_ on Friday January 28, 2022 @08:11AM (#30114119)
Dubious. I prefer that style myself, but there's a lot of value in squashing multiple commits around a feature into a single, "this commit implements this feature" commit. Is it valuable to retain the entire development history of a feature, or just the feature itself? What if during the development, it was rewritten a dozen times? What if there's a dozen commits where the author meandered and only in the last three commits got to the point?

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.

Re:Apple contributes to OBS to support screen capture using ... by pferde on Friday January 28, 2022 @08:29AM (#30114288)
Agreed, it's a matter of preference, but I prefer logically separate changes to be in separate commits at least within the PR, where it may make reviewing the PR easier. It's basic empathy towards the reviewer(s).

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.

Re:Apple contributes to OBS to support screen capture using ... by ignoramous on Friday January 28, 2022 @09:05AM (#30114686)
> This blog post is a good description of the most prevalent convention in how to write good and useful messages.

See also:

https://google.github.io/eng-practices/review/developer/cl-d...

https://microsoft.github.io/code-with-engineering-playbook/c...

Re:Apple contributes to OBS to support screen capture using ... by jldugger on Friday January 28, 2022 @12:43PM (#30117899)
> DEFINITELY say what you are doing. And then say why.

My favored github PR template has 3 sections:

  - What does this PR do?
  - Why is that valuable?
  - Link to bug tracker.
Re:Apple contributes to OBS to support screen capture using ... by ihaveajob on Friday January 28, 2022 @12:56PM (#30118085)
We have a similar template at work, and since we made it the default (on Bitbucket you can pre-fill it), it's saved a ton of back and forth asking questions:

* 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)

Re:Apple contributes to OBS to support screen capture using ... by n3_ on Friday January 28, 2022 @05:55AM (#30113076)
In this case it looks their work is based on another branch not yet merged (https://github.com/obsproject/obs-studio/pull/5155 which adds support for Apple Silicon) - and the commit is from there.
Re:Apple contributes to OBS to support screen capture using ... by da_chicken on Friday January 28, 2022 @11:53AM (#30117219)
Yes, and the author was asked to base the PR on 5155:

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.

Re:Apple contributes to OBS to support screen capture using ... by Applejinx on Friday January 28, 2022 @06:23AM (#30113282)
Looking forward to that: I'm going to be needing to use OBS on Apple Silicon.
Re:Apple contributes to OBS to support screen capture using ... by mikkelam on Friday January 28, 2022 @06:29AM (#30113347)
I honestly thought it already was running natively, it already runs super smooth in rosetta
Re:Apple contributes to OBS to support screen capture using ... by ziml77 on Friday January 28, 2022 @10:36AM (#30115902)
Rosetta is incredibly impressive. And I guess it needed to be. The switch to ARM was going to be a hard sell without a fast x86 translation layer. I'm hoping though that devs don't use it as an excuse to never release ARM builds of their software. It would be good to have ARM builds across all the major operating systems.
Re:Apple contributes to OBS to support screen capture using ... by dagmx on Friday January 28, 2022 @06:56PM (#30122189)
I fully expect devs to drag their feet.

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.

Re:Apple contributes to OBS to support screen capture using ... by krallja on Friday January 28, 2022 @08:59AM (#30114614)
Github can point the PR at that branch and those commits won’t show up anymore.
Re:Apple contributes to OBS to support screen capture using ... by timdorr on Friday January 28, 2022 @11:22AM (#30116685)
That branch is on a different fork (PatTheMav's), so they wouldn't be able to do that in this case.
Re:Apple contributes to OBS to support screen capture using ... by krallja on Saturday January 29, 2022 @10:15AM (#30126913)
TIL. Thanks.
Re:Apple contributes to OBS to support screen capture using ... by donatj on Friday January 28, 2022 @08:30AM (#30114308)
We have a rule internally that a PR can’t be more than 1,000 loc. I personally find a 1,000 loc PR almost unreviewable. It takes me multiple days and a stack of notes, and still almost always ends up with effects I didn’t anticipate.

Trying to understand the changes and their full implications is nearly impossible. 100 loc is a better top end imho.

Re:Apple contributes to OBS to support screen capture using ... by coldcode on Friday January 28, 2022 @09:11AM (#30114760)
Last place I worked (big company, not FAANG) I remember a PR for our main app that affected 500 files and occasionally dozens of places in some of them. All the reviews were "LGTM".
Re:Apple contributes to OBS to support screen capture using ... by ascagnel_ on Friday January 28, 2022 @09:16AM (#30114828)
I forget where I first saw it, but there's a joke of "ten lines, ten issues; 1,000 lines, looks good". There's a human limit to how much you can hold in your head when reviewing code.
Re:Apple contributes to OBS to support screen capture using ... by thetallstick on Friday January 28, 2022 @03:07PM (#30119658)
Looks like the programmer's version of: "If you owe the bank $100, that's your problem. If you owe the bank $100 million, that's the bank's problem.”

https://www.goodreads.com/quotes/214064-if-you-owe-the-bank-...

Re:Apple contributes to OBS to support screen capture using ... by whimsicalism on Friday January 28, 2022 @12:53PM (#30118040)
I think it's a double edged sword - people are also way too nitty for small commits, which only incentivizes behavior like this.
Re:Apple contributes to OBS to support screen capture using ... by doix on Friday January 28, 2022 @10:14AM (#30115572)
When you refactor a commonly used structure, it's easily possible to hit situations that you described. In those cases, having nicely organized commits are super important. You need to make sure that the commit that does the refactor only does the refactoring. Nothing else, then you can review the PR commit by commit and it becomes much more manageable.

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 :).

Re:Apple contributes to OBS to support screen capture using ... by lulzury on Friday January 28, 2022 @10:31AM (#30115839)
10 lines of code = 10 issues. 500 lines of code = "looks fine."
Re:Apple contributes to OBS to support screen capture using ... by travisgriggs on Friday January 28, 2022 @04:07PM (#30120384)
Parkinson’s Law of Triviality
Re:Apple contributes to OBS to support screen capture using ... by Cullinet on Friday January 28, 2022 @10:42AM (#30115996)
about days and a stack of notes :

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.

Re:Apple contributes to OBS to support screen capture using ... by dlsa on Friday January 28, 2022 @02:29PM (#30119229)
Code reviews are interesting to watch. Especially when the author awkwardly pauses and says, "I'm not sure what this code does".
Re:Apple contributes to OBS to support screen capture using ... by rlt on Friday January 28, 2022 @12:43PM (#30117896)
HN: big tech companies should contribute more to open source!

Also HN: no, not like that!

Re:Apple contributes to OBS to support screen capture using ... by dimator on Saturday January 29, 2022 @01:50AM (#30124348)
There's nothing weird about both of those being true.
Re:Apple contributes to OBS to support screen capture using ... by ff133 on Friday January 28, 2022 @05:37AM (#30112956)
Question from a naive kiddo; When the PRs are this big, what are the steps taken to "get it in" the master ? Just blindly accept based on CD/CI jobs, or break it down to walk through every change ? "Ref: supply chain attacks"
Re:Apple contributes to OBS to support screen capture using ... by pilif on Friday January 28, 2022 @05:50AM (#30113043)
If I was in the position of having to review that PR, I would probably flat-out reject it and ask for just the minimal changes required.

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.

Re:Apple contributes to OBS to support screen capture using ... by madmoose on Friday January 28, 2022 @06:44AM (#30113451)
The Apple developer's commit builds upon another pull request which contains the build system work by OBS developers, the build system changes are not part of Apple's commit.
Re:Apple contributes to OBS to support screen capture using ... by kristjansson on Friday January 28, 2022 @04:09PM (#30120396)
A million comments and this is the only valuable one. Amazing that everyone accepted the premise that Apple proposed refactoring some other project’s CI.
Re:Apple contributes to OBS to support screen capture using ... by Diskutant on Friday January 28, 2022 @06:40AM (#30113425)
No, the PR is based on another PR [0] which adds Apple Silicon and Universal Binary builds, the mentioned commit is part of that PR.

[0] https://github.com/obsproject/obs-studio/pull/5155/commits

Re:Apple contributes to OBS to support screen capture using ... by pbhjpbhj on Friday January 28, 2022 @09:01AM (#30114651)
>Apple probably won't have the resources to rework their PR //

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'?

Re:Apple contributes to OBS to support screen capture using ... by Cullinet on Friday January 28, 2022 @10:58AM (#30116281)
I didn't get where I am today by employing engineers with my profits...

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...

Re:Apple contributes to OBS to support screen capture using ... by spockz on Friday January 28, 2022 @06:36AM (#30113395)
It is not that uncommon to have make changes to a build system in many places in order to support a new architecture. Especially if there was previously only support for a single one.
Re:Apple contributes to OBS to support screen capture using ... by michaelt on Friday January 28, 2022 @06:12AM (#30113194)
Doesn't the gigantic pull request description [1] already provide ample description of why the changes are being made?

[1] https://github.com/obsproject/obs-studio/pull/5875

Re:Apple contributes to OBS to support screen capture using ... by kzzzznot on Friday January 28, 2022 @06:26AM (#30113327)
That doesn’t get stored in git, you won’t be able to see that information on the clone of the repository you will be developing on locally.
Re:Apple contributes to OBS to support screen capture using ... by gwd on Friday January 28, 2022 @06:36AM (#30113393)
Just to expand on that, I always say there are three audiences for the commit message:

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.

[1] https://news.ycombinator.com/item?id=30070757

Re:Apple contributes to OBS to support screen capture using ... by whimsicalism on Friday January 28, 2022 @12:54PM (#30118062)
> 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.

Re:Apple contributes to OBS to support screen capture using ... by plorkyeran on Friday January 28, 2022 @01:13PM (#30118320)
A fairly common occurrence when looking at old commits is that any URLs mentioned are now 404s, and ticket numbers are for an issue tracker that no longer exists.
Re:Apple contributes to OBS to support screen capture using ... by cdcarter on Friday January 28, 2022 @01:23PM (#30118430)
Isn't the PR exactly where you'd go to see that information, if you're an org that uses PRs to store that information?
Re:Apple contributes to OBS to support screen capture using ... by lanstin on Friday January 28, 2022 @06:13PM (#30121794)
Unlike commit msgs, which are immutable and stored with the code, Jiras/Githubs etc. are transient.
Re:Apple contributes to OBS to support screen capture using ... by timdorr on Friday January 28, 2022 @11:22AM (#30116696)
It's in the commit message, so it will get stored: https://github.com/obsproject/obs-studio/pull/5875/commits/5...
Re:Apple contributes to OBS to support screen capture using ... by progbits on Friday January 28, 2022 @06:15AM (#30113210)
None of that is part of the Git repo, so any mirrors won't have the context.
Re:Apple contributes to OBS to support screen capture using ... by madmoose on Friday January 28, 2022 @06:39AM (#30113411)
Re:Apple contributes to OBS to support screen capture using ... by steerablesafe on Friday January 28, 2022 @06:02AM (#30113123)
Just to chip in what should the commit message say: it should express the intent of the change and the reason of the change (latter could be reference to ticket). I don't think expressing how the intended change is achieved is important, that's what the diff is. If it's not clear in the diff how the intended change is achieved, try adding some comments.
Re:Apple contributes to OBS to support screen capture using ... by disintegrator on Friday January 28, 2022 @05:26AM (#30112875)
I'm all for well presented PRs/commits but I'm not sure how a good commit message mitigates the risk of a supply chain attack in this case.
Re:Apple contributes to OBS to support screen capture using ... by pilif on Friday January 28, 2022 @05:32AM (#30112915)
It might help the reviewer to not flat-out reject the PR because it gives them a fame of mind as to what the intention of the change is.
Re:Apple contributes to OBS to support screen capture using ... by Joeri on Saturday January 29, 2022 @07:50AM (#30125871)
Never say what you ware doing (it's obvious this commit is updating build scripts). Say why you are doing it

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.

Re:Apple contributes to OBS to support screen capture using ... by emptybottle on Friday January 28, 2022 @09:34AM (#30115061)
Yes, a good commit message should be a few concise paragraphs.

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.

Re:Apple contributes to OBS to support screen capture using ... by fnord77 on Friday January 28, 2022 @03:26PM (#30119879)
in the description of the PR, there's almost 1000 words of text describing in detail what is being done. I don't see the problem.
Re:Apple contributes to OBS to support screen capture using ... by i386 on Friday January 28, 2022 @07:02AM (#30113587)
Seems pretty fucking clear based on the message to me.
Re:Apple contributes to OBS to support screen capture using ... by ricardobeat on Friday January 28, 2022 @09:11AM (#30114767)
Note that those commits seem to have been added by an OBS contributor on top of Apple's patch. The fact they touch the entire build system, in a PR that is 100% macOS focused, is much more concerning than the commit messages.