[webkit-dev] WebKit Transition to Git

[Ryosuke Niwa]

On Tue, Oct 13, 2020 at 1:57 PM Michael Catanzaro <mcatanzaro at gnome.org> wrote:
>
> On Tue, Oct 13, 2020 at 12:32 pm, Maciej Stachowiak <mjs at apple.com>
> wrote:
> > I’m assuming your objection is to regular merges, but how do you
> > feel about squash merges? Or do you think all PRs should be landed by
> > rebasing?
>
> If we want a linear history (we do), all PRs ultimately have to land as
> fast-forward merges, one way or the other. I think rebasing is the
> simplest way to accomplish that, but squashes work too if all your
> changes are sufficiently self-contained to land as one commit.
>
> I suggest leaving this up to the discretion of the developer and
> reviewer rather than mandating one way or the other, because there are
> advantages and disadvantages to both approaches. If your local commit
> history is a mess, sometimes squashing it all into one commit is an
> easy way to make it acceptable for upstream. If you hate rewriting
> history to make it look good, and your MR isn't too huge, a squash
> might be appropriate. But more often than not, I'd say that would
> result in a worse commit history.

FWIW, I think we should always squash all commits and have a single
change log entry / commit message for all changes.

In the case we want to rebase and keep multiple commits, then we
should have a change log / descriptive commit message that follows the
current change log format for each commit, rather than a short
description of each change.

> > My own preference would be to require squash merge, because it keeps
> > the history simple for the main branch, but does not risk putting
> > intermediate revisions which may work or even build on the main
> > branch.
>
> The disadvantage is that if you squash before merging, you encourage
> fewer, bigger commits that might be harder to read and potentially much
> less fun to discover at the end of a bisect.

Not squashing only helps if each commit can stand on its own. At that
point, I'd suggest such a sequence of commits be made into multiple
PRs instead of multiple commits in a single PR, each of which requires
a separate code review.

> On the other hand, if you don't squash, it's indeed possible that your
> commit history might be messy, e.g. intermediate commits might break
> tests fixed by subsequent commits, or intermediate commits might not
> build at all.

This to me is a show stopper. When I'm trying to bisect an issue,
etc..., the biggest obstacle I face is any intermediate revisions
where builds are broken or otherwise non-functional. I don't think we
should let anyone merge a commit into the main branch unless the
commit meets the same standards as a regular Bugzilla patch we land
today.

> Sometimes I see the
> opposite, where too many changes are bundled into one big commit. (This
> is more common in WebKit, since we normally try to have one patch per
> bug, and splitting changes into multiple bugs is inconvenient.) But
> usually the developer submitting a MR has found a good balance between
> the two extremes. Ultimately, what's most important is landing a clean
> commit history with reviewable commits. Again, the scope of commits is
> subject to review just like code changes are.

I often review test changes in WPT or spec changes in WHATWG / W3C,
and I often find a PR with multiple commits to be annoying to review.
I'd rather have each PR have a single large commit to review. In
practice, I'd never review commit by commit because I need to see the
whole picture to review what's happening.

> Instead, I suggest
> developers should aggressively use 'git add -p' and 'git rebase -i' to
> selectively commit, rewrite, and reorder history to look good before
> opening the MR. This isn't optional for most open source projects: if
> you propose an MR with ugly commit history, it won't be merged until
> fixed. For a typical MR of moderate complexity, I'll use 'git rebase
> -i' at least a couple times before the history is clean enough for a
> MR, and to make fixup commits disappear into the most-appropriate
> commit in the sequence.

I'm afraid that this will still result in random intermediary commits
being merged into the main branch because there is no mechanical
enforcement.

> Regarding commit messages, I don't understand why there's any
> expectation that they need to be checked into files in order to be
> detailed and complete. If a commit message doesn't adequately describe
> what it's fixing, then the reviewer should open a review thread to
> complain and request more detailed commit messages.

The problem is that I've seen multiple projects which moved to Git and
did this, and their commit log message's quality materially degraded.
If GitHub and other tools allowed inline comments being added for each
line of the commit message, I have less of concern. Github doesn't.

> If a change is very
> straightforward and obvious, sometimes a quick sentence might suffice,
> but usually a good commit message should be at least a paragraph or
> two, and often more. Function-level ChangeLog-style details are hard to
> read and rarely helpful.

I disagree. Detailed descriptions and function-level change logs are
exactly what I use to dig up all the code history and figure out
what's causing the bug and how to fix in numerous occasions. Not
having that would be a massive regression.

- R. Niwa