Re: [PATCH v3] Add a document on rebasing and merging

[Dmitry Vyukov]

On Wed, Jun 12, 2019 at 5:45 PM Jonathan Corbet <corbet@xxxxxxx> wrote:
>
> 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.
>
> Acked-by: David Rientjes <rientjes@xxxxxxxxxx>
> Signed-off-by: Jonathan Corbet <corbet@xxxxxxx>
> ---
> 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
>
> diff --git a/Documentation/maintainer/index.rst b/Documentation/maintainer/index.rst
> index 2a14916930cb..56e2c09dfa39 100644
> --- a/Documentation/maintainer/index.rst
> +++ b/Documentation/maintainer/index.rst
> @@ -10,5 +10,6 @@ additions to this manual.
>     :maxdepth: 2
>
>     configure-git
> +   rebasing-and-merging
>     pull-requests
>
> diff --git a/Documentation/maintainer/rebasing-and-merging.rst b/Documentation/maintainer/rebasing-and-merging.rst
> new file mode 100644
> index 000000000000..5da9da7a2c51
> --- /dev/null
> +++ b/Documentation/maintainer/rebasing-and-merging.rst
> @@ -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
> +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