€•<’Œsphinx.addnodes”Œdocument”“”)”}”(Œ rawsource”Œ”Œchildren”]”(Œ translations”Œ LanguagesNode”“”)”}”(hhh]”(hŒ pending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”(hhŒparent”hubaŒ attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ refdomain”Œstd”Œreftype”Œdoc”Œ reftarget”Œ3/translations/zh_CN/maintainer/rebasing-and-merging”Œmodname”NŒ classname”NŒ refexplicit”ˆuŒtagname”hhh ubh)”}”(hhh]”hŒChinese (Traditional)”…””}”(hhhh2ubah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ3/translations/zh_TW/maintainer/rebasing-and-merging”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒItalian”…””}”(hhhhFubah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ3/translations/it_IT/maintainer/rebasing-and-merging”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒJapanese”…””}”(hhhhZubah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ3/translations/ja_JP/maintainer/rebasing-and-merging”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒKorean”…””}”(hhhhnubah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ3/translations/ko_KR/maintainer/rebasing-and-merging”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒSpanish”…””}”(hhhh‚ubah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ3/translations/sp_SP/maintainer/rebasing-and-merging”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h hhŒ _document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”(hhhh£ubah}”(h]”h ]”h"]”h$]”h&]”Œ xml:space”Œpreserve”uh1h¡hhhžhhŸŒM/var/lib/git/docbuild/linux/Documentation/maintainer/rebasing-and-merging.rst”h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒRebasing and merging”h]”hŒRebasing and merging”…””}”(hh½hh»hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh¶hžhhŸh³h KubhŒ paragraph”“”)”}”(hX¿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.”h]”hX¿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.”…””}”(hhÍhhËhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhÊ)”}”(hXwOne 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.”h]”hXwOne 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.”…””}”(hhÛhhÙhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhµ)”}”(hhh]”(hº)”}”(hŒRebasing”h]”hŒRebasing”…””}”(hhìhhêhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hhçhžhhŸh³h KubhÊ)”}”(hX"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:”h]”(hŒÍ“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 ”…””}”(hŒÉ"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 ”hhøhžhhŸNh NubhŒliteral”“”)”}”(hŒ``git rebase``”h]”hŒ git rebase”…””}”(hhhjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhhøubhŒ= command, but there are significant differences between them:”…””}”(hŒ= command, but there are significant differences between them:”hhøhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KhhçhžhubhŒ block_quote”“”)”}”(hhh]”hŒ bullet_list”“”)”}”(hhh]”(hŒ list_item”“”)”}”(hXChanging 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. ”h]”hÊ)”}”(hXChanging 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.”h]”hX!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.”…””}”(hj.hj,hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khj(ubah}”(h]”h ]”h"]”h$]”h&]”uh1j&hj#ubj')”}”(hXChanging 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" ”h]”hÊ)”}”(hXChanging 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"”h]”hXChanging 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—…””}”(hjFhjDhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K$hj@ubah}”(h]”h ]”h"]”h$]”h&]”uh1j&hj#ubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1j!hŸh³h Khjubah}”(h]”h ]”h"]”h$]”h&]”uh1jhhçhžhhŸNh NubhÊ)”}”(hŒØ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.”h]”hŒÜ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.”…””}”(hjhhjfhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K)hhçhžhubhÊ)”}”(hŒ^There are a few rules of thumb that can help developers to avoid the worst perils of rebasing:”h]”hŒ^There are a few rules of thumb that can help developers to avoid the worst perils of rebasing:”…””}”(hjvhjthžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K-hhçhžhubj)”}”(hhh]”j")”}”(hhh]”(j')”}”(hXç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. ”h]”(hÊ)”}”(hXIHistory 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.”h]”hXIHistory 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.”…””}”(hjŽhjŒhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K0hjˆubhÊ)”}”(hX›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.”h]”hX›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.”…””}”(hjœhjšhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K6hjˆubeh}”(h]”h ]”h"]”h$]”h&]”uh1j&hj…ubj')”}”(hX]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. ”h]”hÊ)”}”(hX\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.”h]”hX^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.”…””}”(hj´hj²hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K=hj®ubah}”(h]”h ]”h"]”h$]”h&]”uh1j&hj…ubj')”}”(hŒ£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. ”h]”hÊ)”}”(hŒ¢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.”h]”hŒ¢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.”…””}”(hjÌhjÊhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KChjÆubah}”(h]”h ]”h"]”h$]”h&]”uh1j&hj…ubj')”}”(hXwIf 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. ”h]”hÊ)”}”(hXvIf 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.”h]”hXvIf 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.”…””}”(hjähjâhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KGhjÞubah}”(h]”h ]”h"]”h$]”h&]”uh1j&hj…ubj')”}”(hX4Realize 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. ”h]”hÊ)”}”(hX3Realize 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.”h]”hX3Realize 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.”…””}”(hjühjúhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KNhjöubah}”(h]”h ]”h"]”h$]”h&]”uh1j&hj…ubeh}”(h]”h ]”h"]”h$]”h&]”j^j_uh1j!hŸh³h K0hj‚ubah}”(h]”h ]”h"]”h$]”h&]”uh1jhhçhžhhŸNh NubhÊ)”}”(hXGA 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.”h]”hXGA 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.”…””}”(hjhjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KThhçhžhubhÊ)”}”(hŒ 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.”h]”hŒ 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.”…””}”(hj*hj(hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KZhhçhžhubeh}”(h]”Œrebasing”ah ]”h"]”Œrebasing”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒMerging”h]”hŒMerging”…””}”(hjChjAhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj>hžhhŸh³h K_ubhÊ)”}”(hXº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.”h]”hXº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.”…””}”(hjQhjOhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kahj>hžhubhÊ)”}”(hŒò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.”h]”hŒò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.”…””}”(hj_hj]hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khhj>hžhubhÊ)”}”(hŒÝ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.”h]”hŒÝ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.”…””}”(hjmhjkhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kmhj>hžhubhµ)”}”(hhh]”(hº)”}”(hŒMerging from lower-level trees”h]”hŒMerging from lower-level trees”…””}”(hj~hj|hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjyhžhhŸh³h KrubhÊ)”}”(hX‰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.”h]”(hX 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 ”…””}”(hX 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 ”hjŠhžhhŸNh NubhŒemphasis”“”)”}”(hŒ*why*”h]”hŒwhy”…””}”(hhhj•hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j“hjŠubhŒ the merge is being done. For a lower-level tree, “why†is usually a summary of the changes that will come with that pull.”…””}”(hŒ{ the merge is being done. For a lower-level tree, "why" is usually a summary of the changes that will come with that pull.”hjŠhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KthjyhžhubhÊ)”}”(hŒä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.”h]”hŒä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.”…””}”(hj°hj®hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K~hjyhžhubhÊ)”}”(hŒ¤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.”h]”hŒ¦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.”…””}”(hj¾hj¼hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kƒhjyhžhubeh}”(h]”Œmerging-from-lower-level-trees”ah ]”h"]”Œmerging from lower-level trees”ah$]”h&]”uh1h´hj>hžhhŸh³h Krubhµ)”}”(hhh]”(hº)”}”(hŒ&Merging from sibling or upstream trees”h]”hŒ&Merging from sibling or upstream trees”…””}”(hj×hjÕhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjÒhžhhŸh³h KˆubhÊ)”}”(hX"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.”h]”hX$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.”…””}”(hjåhjãhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KŠhjÒhžhubhÊ)”}”(hXMIt 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.”h]”hXQIt 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.”…””}”(hjóhjñhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KhjÒhžhubhÊ)”}”(hXÑ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.”h]”hXÑ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.”…””}”(hjhjÿhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K•hjÒhžhubhÊ)”}”(hXThat 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.”h]”(hŒYThat said, back merges are occasionally required; when that happens, be sure to document ”…””}”(hŒYThat said, back merges are occasionally required; when that happens, be sure to document ”hj hžhhŸNh Nubj”)”}”(hŒ*why*”h]”hŒwhy”…””}”(hhhjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j“hj ubhX! 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.”…””}”(hX! 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.”hj hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KhjÒhžhubhÊ)”}”(hXwOne 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.”h]”hXwOne 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.”…””}”(hj1hj/hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K¤hjÒhžhubhÊ)”}”(hXö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.”h]”(hXUSo 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 ”…””}”(hXUSo 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 ”hj=hžhhŸNh Nubj”)”}”(hŒ *separate*”h]”hŒseparate”…””}”(hhhjFhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j“hj=ubhŒ— 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.”…””}”(hŒ— 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.”hj=hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K®hjÒhžhubhÊ)”}”(hŒö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.”h]”hŒø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.”…””}”(hjahj_hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K¶hjÒhžhubhÊ)”}”(hX{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.”h]”hX{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.”…””}”(hjohjmhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K»hjÒhžhubhÊ)”}”(hXæ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.”h]”hXæ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.”…””}”(hj}hj{hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KÂhjÒhžhubeh}”(h]”Œ&merging-from-sibling-or-upstream-trees”ah ]”h"]”Œ&merging from sibling or upstream trees”ah$]”h&]”uh1h´hj>hžhhŸh³h Kˆubeh}”(h]”Œmerging”ah ]”h"]”Œmerging”ah$]”h&]”uh1h´hh¶hžhhŸh³h K_ubhµ)”}”(hhh]”(hº)”}”(hŒFinally”h]”hŒFinally”…””}”(hjžhjœhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj™hžhhŸh³h KÏubhÊ)”}”(hXIt 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::”h]”hXŒ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:”…””}”(hXŒ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:”hjªhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KÑhj™hžhubhŒ literal_block”“”)”}”(hŒgit merge --ff-only v5.2-rc1”h]”hŒgit merge --ff-only v5.2-rc1”…””}”(hhhj»ubah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j¹hŸh³h KØhj™hžhubhÊ)”}”(hXnThe 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.”h]”hXnThe 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.”…””}”(hjËhjÉhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KÚhj™hžhubeh}”(h]”Œfinally”ah ]”h"]”Œfinally”ah$]”h&]”uh1h´hh¶hžhhŸh³h KÏubeh}”(h]”Œrebasing-and-merging”ah ]”h"]”Œrebasing and merging”ah$]”h&]”uh1h´hhhžhhŸh³h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒ current_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¹NŒ generator”NŒ datestamp”NŒ source_link”NŒ source_url”NŒ toc_backlinks”Œentry”Œfootnote_backlinks”KŒ sectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒ strip_classes”NŒ report_level”KŒ halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ traceback”ˆŒinput_encoding”Œ utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j Œerror_encoding”ŒUTF-8”Œerror_encoding_error_handler”Œbackslashreplace”Œ language_code”Œen”Œrecord_dependencies”NŒconfig”NŒ id_prefix”hŒauto_id_prefix”Œid”Œ dump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ _destination”NŒ _config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒpep_references”NŒ pep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒ rfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ tab_width”KŒtrim_footnote_reference_space”‰Œfile_insertion_enabled”ˆŒ raw_enabled”KŒline_length_limit”M'Œsyntax_highlight”Œlong”Œ smart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œ docinfo_xform”KŒsectsubtitle_xform”‰Œ image_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œ embed_images”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(jäjáj;j8j–j“jÏjÌjŽj‹jÜjÙuŒ nametypes”}”(jäNj;Nj–NjÏNjŽNjÜNuh}”(jáh¶j8hçj“j>jÌjyj‹jÒjÙj™uŒ footnote_refs”}”Œ citation_refs”}”Œ autofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ footnotes”]”Œ citations”]”Œautofootnote_start”KŒsymbol_footnote_start”KŒ id_counter”Œ collections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œ transformer”NŒ include_log”]”Œ decoration”Nhžhub.