Rebasing and Merging

Rebase와 merge의 기본 관점

Subsystem을 유지하려면 Git source-code management system에 익숙해야 합니다. Git의 강력한 기능은 사용하는 방법에 따라 history를 명확하게 만들 수도, maintainer를 곤란하게 만들 수도 있습니다. 이 문서는 특히 rebase와 merge의 올바른 사용을 다룹니다.

다른 많은 프로젝트와 달리 kernel community는 development history의 merge commit을 두려워하지 않습니다. Project 규모를 고려하면 merge를 피하는 것 자체가 거의 불가능합니다.

Maintainer 문제의 일부는 merge를 무조건 피하려는 데서 생기고, 다른 일부는 너무 자주 merge하는 데서 생깁니다. 목표는 merge commit의 개수를 최소화하는 것이 아니라 history와 책임을 정확히 보존하는 것입니다.

.. 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.  Some problems encountered by
maintainers result from a desire to avoid merges, while others come from
merging a little too often.

Rebase의 두 유형

Rebase는 repository 안의 commit series history를 바꾸는 과정입니다. 둘 다 `git rebase` 명령으로 수행되지만 의미가 크게 다른 두 작업이 있습니다.

첫째는 patch series의 parent, 즉 시작 commit을 바꾸는 것입니다. 이전 kernel release를 base로 만든 patchset을 현재 release 위로 옮기는 경우이며, 이 문서에서는 `reparenting`이라고 부릅니다.

둘째는 깨진 commit을 고치거나 삭제하고, patch를 추가하고, commit changelog에 tag를 넣고, 적용 순서를 바꾸는 작업입니다. 이를 `history modification`이라고 부릅니다.

적절한 rebase는 development history를 더 깨끗하고 명료하게 하지만, 잘못 사용하면 history를 가리고 bug를 만들 수 있습니다.

Rebasing
========

"Rebasing" is the process of changing the history of a series of commits
within a repository.  There are two different types of operations that are
referred to as rebasing since both are done with the ``git rebase``
command, but there are significant differences between them:

 - Changing the parent (starting) commit upon which a series of patches is
   built.  For example, a rebase operation could take a patch set built on
   the previous kernel release and base it, instead, on the current
   release.  We'll call this operation "reparenting" in the discussion
   below.

 - Changing the history of a set of patches by fixing (or deleting) broken
   commits, adding patches, adding tags to commit changelogs, or changing
   the order in which commits are applied.  In the following text, this
   type of operation will be referred to as "history modification"

The term "rebasing" will be used to refer to both of the above operations.
Used properly, rebasing can yield a cleaner and clearer development
history; used improperly, it can obscure that history and introduce bugs.

안전한 rebase 규칙

Private system 밖에 공개한 history는 보통 바꾸면 안 됩니다. 다른 개발자가 이미 tree를 가져가 그 위에 작업했을 수 있기 때문입니다. Rebase가 필요한 work라면 아직 public repository에 commit할 준비가 되지 않았다는 신호인 경우가 많습니다.

예외도 있습니다. `linux-next`처럼 성격상 자주 rebase되는 tree는 개발자가 base로 삼지 말아야 함을 알고 있습니다. Test나 자동화 서비스를 위해 unstable branch를 공개할 수도 있지만, 사용자가 그 위에 work를 쌓지 않도록 명확히 알려야 합니다.

다른 사람이 만든 history가 포함된 branch는 rebase하면 안 됩니다. 다른 repository에서 변경을 pull한 순간 그 history의 custodian이 됩니다. 이런 tree의 broken commit은 history에서 지우지 말고 명시적인 revert로 남기는 것이 원칙입니다.

단지 더 새 base에 있고 싶거나 upstream merge를 피하고 싶다는 이유로 tree를 reparent해서는 안 됩니다.

Reparent가 꼭 필요하다면 임의의 kernel commit을 새 base로 고르지 않습니다. Release 사이의 kernel은 상대적으로 불안정할 수 있으므로 `-rc` release 같은 잘 알려진 stable point를 선택합니다.

Reparenting이나 큰 history modification은 개발·test가 이루어진 환경을 바꾸고 기존 test의 상당 부분을 무효화할 수 있습니다. Reparented patch series는 새 code처럼 취급해 처음부터 다시 test해야 합니다.

Pull request 직전에 random commit으로 reparent된 series는 충분히 test됐을 가능성도, Linus가 처리할 가능성도 낮습니다. 반대로 private tree에만 rebase를 제한하고 잘 알려진 시작점과 충분한 test를 사용하면 위험이 낮습니다.

There are a few rules of thumb that can help developers to avoid the worst
perils of rebasing:

 - History that has been exposed to the world beyond your private system
   should usually not be changed.  Others may have pulled a copy of your
   tree and built on it; modifying your tree will create pain for them.  If
   work is in need of rebasing, that is usually a sign that it is not yet
   ready to be committed to a public repository.

   That said, there are always exceptions.  Some trees (linux-next being
   a significant example) are frequently rebased by their nature, and
   developers know not to base work on them.  Developers will sometimes
   expose an unstable branch for others to test with or for automated
   testing services.  If you do expose a branch that may be unstable in
   this way, be sure that prospective users know not to base work on it.

 - Do not rebase a branch that contains history created by others.  If you
   have pulled changes from another developer's repository, you are now a
   custodian of their history.  You should not change it.  With few
   exceptions, for example, a broken commit in a tree like this should be
   explicitly reverted rather than disappeared via history modification.

 - Do not reparent a tree without a good reason to do so.  Just being on a
   newer base or avoiding a merge with an upstream repository is not
   generally a good reason.

 - If you must reparent a repository, do not pick some random kernel commit
   as the new base.  The kernel is often in a relatively unstable state
   between release points; basing development on one of those points
   increases the chances of running into surprising bugs.  When a patch
   series must move to a new base, pick a stable point (such as one of
   the -rc releases) to move to.

 - Realize that reparenting a patch series (or making significant history
   modifications) changes the environment in which it was developed and,
   likely, invalidates much of the testing that was done.  A reparented
   patch series should, as a general rule, be treated like new code and
   retested from the beginning.

A frequent cause of merge-window trouble is when Linus is presented with a
patch series that has clearly been reparented, often to a random commit,
shortly before the pull request was sent.  The chances of such a series
having been adequately tested are relatively low - as are the chances of
the pull request being acted upon.

If, instead, rebasing is limited to private trees, commits are based on a
well-known starting point, and they are well tested, the potential for
trouble is low.

Kernel에서 merge가 필요한 이유

Merge는 kernel development의 흔한 작업입니다. 5.1 development cycle에는 전체의 거의 9%인 1,126개 merge commit이 있었습니다.

Kernel work는 100개가 넘는 subsystem tree에 모이고 각 tree는 여러 topic branch를 가질 수 있습니다. Branch들은 독립적으로 개발되므로 upstream repository에 들어가기 전에 최소 한 번은 자연스럽게 merge됩니다.

Pull request branch를 current trunk 위로 rebase해 merge commit을 없애도록 요구하는 프로젝트도 있지만 kernel은 그렇지 않습니다. Merge를 피하려고 branch를 rebase하면 문제가 생길 가능성이 큽니다.

Subsystem maintainer가 하는 merge는 lower-level subsystem tree에서 받는 경우와 sibling tree 또는 mainline에서 받는 경우로 나뉘며, 두 상황의 모범 사례가 다릅니다.

Merging
=======

Merging is a common operation in the kernel development process; the 5.1
development cycle included 1,126 merge commits - nearly 9% of the total.
Kernel work is accumulated in over 100 different subsystem trees, each of
which may contain multiple topic branches; each branch is usually developed
independently of the others.  So naturally, at least one merge will be
required before any given branch finds its way into an upstream repository.

Many projects require that branches in pull requests be based on the
current trunk so that no merge commits appear in the history.  The kernel
is not such a project; any rebasing of branches to avoid merges will, most
likely, lead to trouble.

Subsystem maintainers find themselves having to do two types of merges:
from lower-level subsystem trees and from others, either sibling trees or
the mainline.  The best practices to follow differ in those two situations.

Lower-level tree merge

큰 subsystem은 maintainer 계층이 여러 단계이고 lower-level maintainer가 상위 maintainer에게 pull request를 보냅니다. 이를 처리하면 merge commit이 생기는 것이 정상입니다.

Fast-forward가 가능한 드문 경우에도 merge 이유를 기록하려고 `--no-ff`를 사용해 merge commit을 강제로 만들 수 있습니다. 모든 merge changelog는 왜 merge하는지 설명해야 하며, lower-level tree에서는 보통 pull로 들어오는 변경의 요약이 그 이유입니다.

모든 단계의 maintainer는 pull request에 signed tag를 사용해야 하고 upstream maintainer는 branch를 가져올 때 tag를 검증해야 합니다. 이를 생략하면 development process 전체의 보안을 위협합니다.

다른 사람의 history를 자신의 tree에 merge한 뒤에는 원래 rebase가 가능했더라도 그 branch를 다시 rebase할 수 없습니다.

Merging from lower-level trees
------------------------------

Larger subsystems tend to have multiple levels of maintainers, with the
lower-level maintainers sending pull requests to the higher levels.  Acting
on such a pull request will almost certainly generate a merge commit; that
is as it should be.  In fact, subsystem maintainers may want to use
the --no-ff flag to force the addition of a merge commit in the rare cases
where one would not normally be created so that the reasons for the merge
can be recorded.  The changelog for the merge should, for any kind of
merge, say *why* the merge is being done.  For a lower-level tree, "why" is
usually a summary of the changes that will come with that pull.

Maintainers at all levels should be using signed tags on their pull
requests, and upstream maintainers should verify the tags when pulling
branches.  Failure to do so threatens the security of the development
process as a whole.

As per the rules outlined above, once you have merged somebody else's
history into your tree, you cannot rebase that branch, even if you
otherwise would be able to.

Sibling·upstream tree와 back merge

Downstream merge는 일반적이지만 sibling이나 다른 tree를 merge한 branch를 upstream으로 보내는 것은 warning sign입니다. 충분히 생각하고 정당화하지 않으면 이후 pull request가 거부될 수 있습니다.

Master branch를 자신의 repository로 merge하는 `back merge`는 parallel development conflict를 확인하고 최신 상태라는 안도감을 주지만 거의 항상 피해야 합니다.

Back merge는 자신의 branch history를 흐리고 community 다른 영역의 bug를 가져올 가능성을 높이며, 담당 work가 stable하고 upstream 준비가 됐는지 확인하기 어렵게 합니다. 잦은 merge는 관리가 잘 된 branch에서 없어야 할 tree 간 interaction 문제까지 숨길 수 있습니다.

가끔 back merge가 필요하면 commit message에 이유를 기록하고 random commit이 아니라 잘 알려진 stable point를 merge합니다. 자신의 immediate upstream보다 더 높은 tree를 직접 back merge해서는 안 되며, 필요하다면 immediate upstream tree가 먼저 수행해야 합니다.

Merging from sibling or upstream trees
--------------------------------------

While merges from downstream are common and unremarkable, merges from other
trees tend to be a red flag when it comes time to push a branch upstream.
Such merges need to be carefully thought about and well justified, or
there's a good chance that a subsequent pull request will be rejected.

It is natural to want to merge the master branch into a repository; this
type of merge is often called a "back merge".  Back merges can help to make
sure that there are no conflicts with parallel development and generally
gives a warm, fuzzy feeling of being up-to-date.  But this temptation
should be avoided almost all of the time.

Why is that?  Back merges will muddy the development history of your own
branch.  They will significantly increase your chances of encountering bugs
from elsewhere in the community and make it hard to ensure that the work
you are managing is stable and ready for upstream.  Frequent merges can
also obscure problems with the development process in your tree; they can
hide interactions with other trees that should not be happening (often) in
a well-managed branch.

That said, back merges are occasionally required; when that happens, be
sure to document *why* it was required in the commit message.  As always,
merge to a well-known stable point, rather than to some random commit.
Even then, you should not back merge a tree above your immediate upstream
tree; if a higher-level back merge is really required, the upstream tree
should do it first.

Conflict 처리와 test merge

Pull request 전에 merge conflict를 해결하려고 upstream을 merge하는 것은 가장 흔한 문제 중 하나이며 반드시 피해야 합니다. 특히 final pull request에서 Linus는 불필요한 back merge보다 conflict를 직접 보는 것을 선호합니다.

Conflict가 보이면 잠재적인 문제 영역을 알 수 있고, Linus는 5.1 cycle에만 382개 merge를 수행했을 만큼 conflict resolution 경험이 많습니다.

Subsystem branch와 mainline 사이 conflict가 예상되면 pull request에서 Linus에게 먼저 경고합니다. 어려운 conflict라면 해결 방법을 보여 주는 별도 branch를 만들어 push하고 요청에 언급하되, 실제 pull request는 merge하지 않은 원래 branch를 대상으로 해야 합니다.

알려진 conflict가 없어도 pull request 전에 local test merge를 하는 것은 좋습니다. Linux-next에서 보지 못한 문제를 찾고 upstream에 요구하는 작업을 정확히 이해하는 데 도움이 됩니다. Test merge 결과를 실제 pull branch에 섞지는 않습니다.

One of the most frequent causes of merge-related trouble is when a
maintainer merges with the upstream in order to resolve merge conflicts
before sending a pull request.  Again, this temptation is easy enough to
understand, but it should absolutely be avoided.  This is especially true
for the final pull request: Linus is adamant that he would much rather see
merge conflicts than unnecessary back merges.  Seeing the conflicts lets
him know where potential problem areas are.  He does a lot of merges (382
in the 5.1 development cycle) and has gotten quite good at conflict
resolution - often better than the developers involved.

So what should a maintainer do when there is a conflict between their
subsystem branch and the mainline?  The most important step is to warn
Linus in the pull request that the conflict will happen; if nothing else,
that demonstrates an awareness of how your branch fits into the whole.  For
especially difficult conflicts, create and push a *separate* branch to show
how you would resolve things.  Mention that branch in your pull request,
but the pull request itself should be for the unmerged branch.

Even in the absence of known conflicts, doing a test merge before sending a
pull request is a good idea.  It may alert you to problems that you somehow
didn't see from linux-next and helps to understand exactly what you are
asking upstream to do.

Cross-tree dependency 해결

Upstream 또는 다른 subsystem tree를 merge하는 또 다른 이유는 dependency 해결입니다. 때로 cross-merge가 최선일 수 있으며 이 경우에도 merge commit은 이유를 설명해야 합니다. Changelog는 실제로 읽히는 기록입니다.

하지만 dependency 문제는 접근 방식을 바꿔야 한다는 신호인 경우가 많습니다. 다른 subsystem tree 전체를 merge하면 그 tree의 bug까지 가져오고, 그 tree가 upstream에 들어가지 못하면 자신의 tree merge도 막힙니다.

더 나은 방법은 두 변경을 한 tree에서 함께 운반하기로 maintainer끼리 합의하거나, prerequisite commit만 담은 topic branch를 만들어 두 tree가 모두 merge하는 것입니다.

Dependency가 큰 infrastructure 변경과 관련되면 dependent commit을 한 development cycle 보류해 prerequisite가 mainline에서 안정화될 시간을 주는 것이 올바를 수 있습니다.

Another reason for doing merges of upstream or another subsystem tree is to
resolve dependencies.  These dependency issues do happen at times, and
sometimes a cross-merge with another tree is the best way to resolve them;
as always, in such situations, the merge commit should explain why the
merge has been done.  Take a moment to do it right; people will read those
changelogs.

Often, though, dependency issues indicate that a change of approach is
needed.  Merging another subsystem tree to resolve a dependency risks
bringing in other bugs and should almost never be done.  If that subsystem
tree fails to be pulled upstream, whatever problems it had will block the
merging of your tree as well.  Preferable alternatives include agreeing
with the maintainer to carry both sets of changes in one of the trees or
creating a topic branch dedicated to the prerequisite commits that can be
merged into both trees.  If the dependency is related to major
infrastructural changes, the right solution might be to hold the dependent
commits for one development cycle so that those changes have time to
stabilize in the mainline.

Cycle 초반 merge와 예외 설명

Development cycle 초반에 tree 다른 곳의 변경과 fix를 받으려고 mainline을 merge하는 것은 비교적 흔합니다. 이때도 random 지점이 아니라 well-known release point를 선택해야 합니다.

Merge window 동안 upstream-bound branch의 내용이 mainline에 완전히 들어가 branch가 비었다면 `git merge --ff-only v5.2-rc1`처럼 fast-forward로 앞으로 당길 수 있습니다.

이 문서의 원칙은 절대 규칙이 아니라 guideline입니다. 다른 해법이 필요한 상황은 항상 존재하며 필요한 일을 막아서는 안 됩니다. 다만 정말 예외가 필요한지 생각하고 비정상적인 작업의 이유를 설명할 준비가 되어 있어야 합니다.

Finally
=======

It is relatively common to merge with the mainline toward the beginning of
the development cycle in order to pick up changes and fixes done elsewhere
in the tree.  As always, such a merge should pick a well-known release
point rather than some random spot.  If your upstream-bound branch has
emptied entirely into the mainline during the merge window, you can pull it
forward with a command like::

  git merge --ff-only v5.2-rc1

The guidelines laid out above are just that: guidelines.  There will always
be situations that call out for a different solution, and these guidelines
should not prevent developers from doing the right thing when the need
arises.  But one should always think about whether the need has truly
arisen and be prepared to explain why something abnormal needs to be done.