Skip to contentSkip to conversation

Add a document on rebasing and merging

PATCH In review Jonathan Corbet 2 participants 4 messages Jun 12, 2019 – Jun 25, 2019

Subsystems (2)
lore
Share & tools
lore

Jonathan Corbet

author maintainer
#0 lore raw

PATCH v3 1/1 Add a document on rebasing and merging

Every merge window seems to involve at least one episode where subsystem maintainers don't manage their trees as Linus would like. Document the expectations so that at least he has something to point people to.

---
I intend to apply this version unless somebody really screams.

Changes in v3
- Fill out discussion on back merges and topic branches as suggested by Jani.

Changes in v2:
- Try to clear up "reparenting" v. "history modification"
- Make the "don't rebase public branches" rule into more of a guideline
- Fix typos noted by Geert
- Rename the document to better reflect its contents

 Documentation/maintainer/index.rst            |   1 +
 .../maintainer/rebasing-and-merging.rst       | 226 ++++++++++++++++++
 2 files changed, 227 insertions(+)
 create mode 100644 Documentation/maintainer/rebasing-and-merging.rst
Documentation/maintainer/index.rst +1 -0
index 2a14916930cb..56e2c09dfa39 100644
@@ -10,5 +10,6 @@ additions to this manual.
    :maxdepth: 2
 
    configure-git
+   rebasing-and-merging
    pull-requests
 
Documentation/maintainer/rebasing-and-merging.rst new file +226 -0

226 lines not on this page · raw message

Signature · 1 line
2.21.0
#1 lore raw
Quoted 50 lines · Jonathan Corbet

Every merge window seems to involve at least one episode where subsystem maintainers don't manage their trees as Linus would like. Document the expectations so that at least he has something to point people to.

---
I intend to apply this version unless somebody really screams.

Changes in v3
- Fill out discussion on back merges and topic branches as suggested by Jani.

Changes in v2:
- Try to clear up "reparenting" v. "history modification"
- Make the "don't rebase public branches" rule into more of a guideline
- Fix typos noted by Geert
- Rename the document to better reflect its contents

 Documentation/maintainer/index.rst            |   1 +
 .../maintainer/rebasing-and-merging.rst       | 226 ++++++++++++++++++
 2 files changed, 227 insertions(+)
 create mode 100644 Documentation/maintainer/rebasing-and-merging.rst
Documentation/maintainer/index.rst +1 -0
index 2a14916930cb..56e2c09dfa39 100644
@@ -10,5 +10,6 @@ additions to this manual.
    :maxdepth: 2
 
    configure-git
+   rebasing-and-merging
    pull-requests
 
Documentation/maintainer/rebasing-and-merging.rst new file +8 -0
new file mode 100644
index 000000000000..5da9da7a2c51
@@ -0,0 +1,226 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================
+Rebasing and merging
+====================
+
+Maintaining a subsystem, as a general rule, requires a familiarity with the
+Git source-code management system.  Git is a powerful tool with a lot of

Documentation/maintainer/rebasing-and-merging.rst line 18

Quoted 10 lines
Documentation/maintainer/rebasing-and-merging.rst new file +10 -0
+features; as is often the case with such tools, there are right and wrong
+ways to use those features.  This document looks in particular at the use
+of rebasing and merging.  Maintainers often get in trouble when they use
+those tools incorrectly, but avoiding problems is not actually all that
+hard.
+
+One thing to be aware of in general is that, unlike many other projects,
+the kernel community is not scared by seeing merge commits in its
+development history.  Indeed, given the scale of the project, avoiding
+merges would be nearly impossible.

Hi Jonathan,

I will appreciate if you elaborate a bit on this "scale of the project". I wondered about reasons for having the current hierarchy of trees and complex merging for a while, but wasn't able to find any rationale. What exactly scale do you mean? I know a number of projects that are comparable to Linux kernel, with the largest being 2 orders of magnitude larger than kernel both in terms of code size and rate of change, that use single tree and linear history. So these scales do not seem to inherently require multiple trees and non-linear history. Maybe this is already documented somewhere?

Thanks

author maintainer
#2 lore raw
Quoted 7 lines · On Fri, 14 Jun 2019 11:59:03 +0200 Dmitry Vyukov <[email protected]> wrote:

I will appreciate if you elaborate a bit on this "scale of the project". I wondered about reasons for having the current hierarchy of trees and complex merging for a while, but wasn't able to find any rationale. What exactly scale do you mean? I know a number of projects that are comparable to Linux kernel, with the largest being 2 orders of magnitude larger than kernel both in terms of code size and rate of change, that use single tree and linear history.

I'm not sure what projects you're talking about, so it's hard to compare.

During the 5.2 merge window, Linus did 209 pulls, bringing in just over 12,000 changesets, from on the order of 1600 developers. Even if, at the beginning of the window, each of those pulls was set up to be a fast-forward, they would no longer be positioned that way once the first pull was done.

Are you really saying that subsystem maintainers should be continuously rebasing their trees to avoid merges at the top level? Do you see how much work that would take, how badly it would obscure the development history, and how many bugs it would introduce? Or perhaps I misunderstood what you're arguing for?

Thanks,

jon

#3 lore raw
Quoted 20 lines · Jonathan Corbet
Quoted 7 lines · On Fri, 14 Jun 2019 11:59:03 +0200 Dmitry Vyukov <[email protected]> wrote:

I will appreciate if you elaborate a bit on this "scale of the project". I wondered about reasons for having the current hierarchy of trees and complex merging for a while, but wasn't able to find any rationale. What exactly scale do you mean? I know a number of projects that are comparable to Linux kernel, with the largest being 2 orders of magnitude larger than kernel both in terms of code size and rate of change, that use single tree and linear history.

I'm not sure what projects you're talking about, so it's hard to compare.

During the 5.2 merge window, Linus did 209 pulls, bringing in just over 12,000 changesets, from on the order of 1600 developers. Even if, at the beginning of the window, each of those pulls was set up to be a fast-forward, they would no longer be positioned that way once the first pull was done.

Quoted 5 lines

Are you really saying that subsystem maintainers should be continuously rebasing their trees to avoid merges at the top level? Do you see how much work that would take, how badly it would obscure the development history, and how many bugs it would introduce? Or perhaps I misunderstood what you're arguing for?

I mean projects like Chromium which seems to be comparable to kernel in code size/rate of change. LLVM, Android are several times smaller, but on the other hand has hundreds times less trees (1). And in particular large monorepos in companies like Google, Facebook, Microsoft. E.g. the Google codebase sees the v5.2 number of changesets in few hours. Although, it's not apples-to-apples with the kernel but shows that scale per-se is not a requirement for multiple trees/non-linear history.
So for the kernel it must a combination of scale + something else (in the process, ownership model, ...). I am trying to understand what is that something else, how inherent it is and what would degrade if kernel switches to single tree/linear history. It would obviously require some adjustments to other parts of the process as well, e.g. you asked what maintainers do with their trees but if there is a single tree, they don't have a tree at all. In most other scalable processes that I am aware of, as much work as possible is pushed down to individual contributors and they do any required rebasing. The closest analog of maintainers only do review and approval. The idea is to remove bottlenecks and distribute process as much as possible to increase scalability. I heard about "maintainer scalability" in the context of the kernel process multiple times.