1 .. SPDX-License-Identifier: GPL-2.0
2
3 ====================
4 Rebasing and merging
5 ====================
6
7 Maintaining a subsystem, as a general rule, re
8 Git source-code management system. Git is a p
9 features; as is often the case with such tools
10 ways to use those features. This document loo
11 of rebasing and merging. Maintainers often ge
12 those tools incorrectly, but avoiding problems
13 hard.
14
15 One thing to be aware of in general is that, u
16 the kernel community is not scared by seeing m
17 development history. Indeed, given the scale
18 merges would be nearly impossible. Some probl
19 maintainers result from a desire to avoid merg
20 merging a little too often.
21
22 Rebasing
23 ========
24
25 "Rebasing" is the process of changing the hist
26 within a repository. There are two different
27 referred to as rebasing since both are done wi
28 command, but there are significant differences
29
30 - Changing the parent (starting) commit upon
31 built. For example, a rebase operation cou
32 the previous kernel release and base it, in
33 release. We'll call this operation "repare
34 below.
35
36 - Changing the history of a set of patches by
37 commits, adding patches, adding tags to com
38 the order in which commits are applied. In
39 type of operation will be referred to as "h
40
41 The term "rebasing" will be used to refer to b
42 Used properly, rebasing can yield a cleaner an
43 history; used improperly, it can obscure that
44
45 There are a few rules of thumb that can help d
46 perils of rebasing:
47
48 - History that has been exposed to the world
49 should usually not be changed. Others may
50 tree and built on it; modifying your tree w
51 work is in need of rebasing, that is usuall
52 ready to be committed to a public repositor
53
54 That said, there are always exceptions. So
55 a significant example) are frequently rebas
56 developers know not to base work on them.
57 expose an unstable branch for others to tes
58 testing services. If you do expose a branc
59 this way, be sure that prospective users kn
60
61 - Do not rebase a branch that contains histor
62 have pulled changes from another developer'
63 custodian of their history. You should not
64 exceptions, for example, a broken commit in
65 explicitly reverted rather than disappeared
66
67 - Do not reparent a tree without a good reaso
68 newer base or avoiding a merge with an upst
69 generally a good reason.
70
71 - If you must reparent a repository, do not p
72 as the new base. The kernel is often in a
73 between release points; basing development
74 increases the chances of running into surpr
75 series must move to a new base, pick a stab
76 the -rc releases) to move to.
77
78 - Realize that reparenting a patch series (or
79 modifications) changes the environment in w
80 likely, invalidates much of the testing tha
81 patch series should, as a general rule, be
82 retested from the beginning.
83
84 A frequent cause of merge-window trouble is wh
85 patch series that has clearly been reparented,
86 shortly before the pull request was sent. The
87 having been adequately tested are relatively l
88 the pull request being acted upon.
89
90 If, instead, rebasing is limited to private tr
91 well-known starting point, and they are well t
92 trouble is low.
93
94 Merging
95 =======
96
97 Merging is a common operation in the kernel de
98 development cycle included 1,126 merge commits
99 Kernel work is accumulated in over 100 differe
100 which may contain multiple topic branches; eac
101 independently of the others. So naturally, at
102 required before any given branch finds its way
103
104 Many projects require that branches in pull re
105 current trunk so that no merge commits appear
106 is not such a project; any rebasing of branche
107 likely, lead to trouble.
108
109 Subsystem maintainers find themselves having t
110 from lower-level subsystem trees and from othe
111 the mainline. The best practices to follow di
112
113 Merging from lower-level trees
114 ------------------------------
115
116 Larger subsystems tend to have multiple levels
117 lower-level maintainers sending pull requests
118 on such a pull request will almost certainly g
119 is as it should be. In fact, subsystem mainta
120 the --no-ff flag to force the addition of a me
121 where one would not normally be created so tha
122 can be recorded. The changelog for the merge
123 merge, say *why* the merge is being done. For
124 usually a summary of the changes that will com
125
126 Maintainers at all levels should be using sign
127 requests, and upstream maintainers should veri
128 branches. Failure to do so threatens the secu
129 process as a whole.
130
131 As per the rules outlined above, once you have
132 history into your tree, you cannot rebase that
133 otherwise would be able to.
134
135 Merging from sibling or upstream trees
136 --------------------------------------
137
138 While merges from downstream are common and un
139 trees tend to be a red flag when it comes time
140 Such merges need to be carefully thought about
141 there's a good chance that a subsequent pull r
142
143 It is natural to want to merge the master bran
144 type of merge is often called a "back merge".
145 sure that there are no conflicts with parallel
146 gives a warm, fuzzy feeling of being up-to-dat
147 should be avoided almost all of the time.
148
149 Why is that? Back merges will muddy the devel
150 branch. They will significantly increase your
151 from elsewhere in the community and make it ha
152 you are managing is stable and ready for upstr
153 also obscure problems with the development pro
154 hide interactions with other trees that should
155 a well-managed branch.
156
157 That said, back merges are occasionally requir
158 sure to document *why* it was required in the
159 merge to a well-known stable point, rather tha
160 Even then, you should not back merge a tree ab
161 tree; if a higher-level back merge is really r
162 should do it first.
163
164 One of the most frequent causes of merge-relat
165 maintainer merges with the upstream in order t
166 before sending a pull request. Again, this te
167 understand, but it should absolutely be avoide
168 for the final pull request: Linus is adamant t
169 merge conflicts than unnecessary back merges.
170 him know where potential problem areas are. H
171 in the 5.1 development cycle) and has gotten q
172 resolution - often better than the developers
173
174 So what should a maintainer do when there is a
175 subsystem branch and the mainline? The most i
176 Linus in the pull request that the conflict wi
177 that demonstrates an awareness of how your bra
178 especially difficult conflicts, create and pus
179 how you would resolve things. Mention that br
180 but the pull request itself should be for the
181
182 Even in the absence of known conflicts, doing
183 pull request is a good idea. It may alert you
184 didn't see from linux-next and helps to unders
185 asking upstream to do.
186
187 Another reason for doing merges of upstream or
188 resolve dependencies. These dependency issues
189 sometimes a cross-merge with another tree is t
190 as always, in such situations, the merge commi
191 merge has been done. Take a moment to do it r
192 changelogs.
193
194 Often, though, dependency issues indicate that
195 needed. Merging another subsystem tree to res
196 bringing in other bugs and should almost never
197 tree fails to be pulled upstream, whatever pro
198 merging of your tree as well. Preferable alte
199 with the maintainer to carry both sets of chan
200 creating a topic branch dedicated to the prere
201 merged into both trees. If the dependency is
202 infrastructural changes, the right solution mi
203 commits for one development cycle so that thos
204 stabilize in the mainline.
205
206 Finally
207 =======
208
209 It is relatively common to merge with the main
210 the development cycle in order to pick up chan
211 in the tree. As always, such a merge should p
212 point rather than some random spot. If your u
213 emptied entirely into the mainline during the
214 forward with a command like::
215
216 git merge --ff-only v5.2-rc1
217
218 The guidelines laid out above are just that: g
219 be situations that call out for a different so
220 should not prevent developers from doing the r
221 arises. But one should always think about whe
222 arisen and be prepared to explain why somethin
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.