[RFC] Make each commit a working version and have linear history.

[alloy]

Proposal:

For each commit in a repo’s mainline branch (a.k.a master branch) to theoretically be deployable; as in, the test suite/linter/etc are all green.

And for related changes to be a single commit or next to each-other in the commit history.

Reasoning

Some of us work more often with a repo’s commit history, either to debug a software issue or otherwise gain information about why certain changes were made. This is made difficult when something that could semantically be considered a single change is spread out over multiple commits.

Squashing before merging means that all the related changes exist in a single commit and thus in context of each other and the commit message.

Each commit a working version

Multiple commits is problematic when trying to find a commit that introduces a change you’re looking for through tools such as git bisect, as there’s the opportunity to come across commits that are known to be broken (which are typically followed up in the PR with a ‘fix‘ commit) and only interrupt the workflow.

Understanding historical decisions

A git merge may result in commits being interleaved with changes from other PRs, which is problematic when scanning the history for changes you may be interested in and having to keep a mental model of all the commits you came across. Especially those that have a commit message such as ‘fix’ only add noise and make this harder than it needs to be.

Exceptions:

In some cases, a PR may contain a larger set of changes that may not all be directly related to each other. In these cases the author should take care to squash the directly related changes into single commits and then request the assignee to ‘Rebase and merge’ instead, which will ensure they will exist next to each-other in the destination branch but otherwise leaves them in tact.

Additional Context:

Some reading material related to topics mentioned:

• https://nl.atlassian.com/git/tutorials/merging-vs-rebasing
• https://www.metaltoad.com/blog/beginners-guide-git-bisect-process-elimination
• https://about.gitlab.com/2018/06/07/keeping-git-commit-history-clean/
• https://blog.carbonfive.com/2017/08/28/always-squash-and-rebase-your-git-commits/
• https://reallifeprogramming.com/git-process-that-works-say-no-to-gitflow-50bf2038ccf7
• https://help.github.com/en/articles/configuring-commit-squashing-for-pull-requests

How is this RFC resolved?

• Offer some form of training on git merge vs rebase basics. (Short L&L?)

• Disable the ’Merge button‘ on repos.

• By default, ‘Squash and merge’ PRs, unless otherwise requested by adding the ‘Rebase and merge’ label.

  Additionally an assignee may be able to glance from the commit history that the few commits are each their own distinct change and can decide to ‘Rebase and merge’ without the author explicitly asking for it.

• Peril’s ‘Merge on green’ feature uses the label to choose either ‘Squash and merge’ or ‘Rebase and merge’.

[alloy]

Some practical information on how to rewrite your commits https://nl.atlassian.com/git/tutorials/rewriting-history

[dleve123]

@alloy is your main goal here to avoid merge commits, or to ensure that there are fewer “WIP”/otherwise poorly named commits in a Git history, or both?

I do think defaulting to a “squash and merge” approach is a useful blunt hammer to reduce “noise” commits, but developing good Git hygiene requires some serious Git-fu (knowing when and how to rebase is a hard thing).

This is all to say that I think some training on rebasing could also be part of resolving this RFC.

[alloy]

@alloy is your main goal here to avoid merge commits, or to ensure that there are fewer “WIP”/otherwise poorly named commits in a Git history, or both?

I’m fine with merge commits. I foremost want commits in mainline to be working versions, so we can use tooling like git bisect without jumping though unnecessary hoops. Second I would appreciate commit messages that provide good context for the change.

It’s a nuanced thing, but I don’t particularly care about hygiene for the sake of it. This RFC is about practical improvements.

This is all to say that I think some training on rebasing could also be part of resolving this RFC.

I don’t think most people will need to do any fancy rebasing, other than normal. But I’m certainly open to doing a (short) L&L on the topic! 👍

[alloy]

Here’s an example of a ‘Squash and merge’ commit vs the original 25 commits.

[damassi]

A lot of (particularly newer) devs are understandably intimidated by rebasing, and in particular dealing with merge conflicts, but this is just a matter of education. If we can help ensure that devs know they can rewind (via something like reflog) and not feel trapped inside of history rewrites then I'm 👍. (I've tried to teach rebases to a few devs in the past found that 100% of the time it seems scary until it's not.)

[ashfurrow]

@alloy that example you linked to makes a really strong case for squash-and-merge as the default option for merging PRs. The 25 commits include several merge commits too, which are also filtered out by squash-and-merge. It effectively turns PRs into those semantic, atomic changes you describe.

I'm a big 👍 on this, and having more resources to improve git skills in general, but I'm unclear why we would need to get everyone to switch to rebasing from master instead of merging? It seems like they get filtered out of history by squash-and-merge.

[alloy]

@ashfurrow I think that only worked out this way because the list of commits ended up being a fast-forward, but I could be wrong about that and I also don’t necessarily know what work GH does under the hood to perform its squash. So perhaps I’ll just drop that part from the RFC, since it was mostly meant as a suggestion to ease work on the dev for longer running branches, which I think is not the norm.

[just-be-dev]

I'm 👍 on squash and merge. I generally default to this already for my own PRs just because I tend to do a lot of WIP commits.

Merge commits seem to work fine. I pretty much never rebase and I haven't had any issues with squash merges to this point.

[alloy]

Good to know, thanks @zephraph!

[jonallured]

I'm totally a plus one on this and I'm pumped that we're discussing this type of thing!!

It appears you are interested in removing the part about squash and merge, which is great because that was the part I was going to push back on as well. I like to artisanally craft my commits and I think there's value in having them outlive their PR so prefer the rebase and merge button. I def strive for each commit to be deployable (and green!) as I have seen the value of being able to bisect in a sane way.

I'll also note too that having a linear history is such a nice thing to work with when digging through commits. So much less brainpower - here's a visual:

Volt on the left and RubyConferences.org on the right where I enforce rebase and merge.

[joeyAghion]

I'm in favor of each git commit corresponding to a theoretically working version. But each commit isn't necessarily releasable; this, in my opinion, is why a pull request is [and should remain] a higher-order concept. I'd much much rather developers work to eliminate crufty commits than we lose that resolution altogether by squashing every PR.

[alloy]

It appears you are interested in removing the part about squash and merge

@jonallured I wasn’t really, I was interested in removing the part about how to best pull in upstream changes into your own branch (and have already done so). For people like you that already make sure to have each commit be a working version and standalone change my suggestion is listed under ‘Exceptions’. My sense was that there’s less people that do this and that the least impact on people in the team would be to make ‘squash and merge’ the default and have people like you and me add the label to not squash. Do you think that makes sense and do you have a suggestion for clarifying that in the RFC (seeing as that was clear enough to you)?

[alloy]

@joeyAghion Me too, but that would definitely require people to better understand how to use git and tools like rebase–which I assumed might be too hard of a requirement. I’m definitely open to having my assumption changed, though.