Rough draft document on merging and rebasing
Subsystems (2)
Jonathan Corbet
maintainerRFC PATCH 1/1 Rough draft document on merging and rebasing
This is a first attempt at following through on last month's discussion about common merging and rebasing errors. The hope here is to document existing best practices rather than trying to define new ones. I've certainly failed somewhere along the way; please set me straight and I'll try to do better next time.
Thanks,
jon
-------------
docs: Add a document on repository management
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.
--- Documentation/maintainer/index.rst | 1 + Documentation/maintainer/repo-hygiene.rst | 195 ++++++++++++++++++++++ 2 files changed, 196 insertions(+) create mode 100644 Documentation/maintainer/repo-hygiene.rst
Documentation/maintainer/index.rst +1 -0
@@ -10,5 +10,6 @@ additions to this manual. :maxdepth: 2 configure-git + repo-hygiene pull-requests
Documentation/maintainer/repo-hygiene.rst new file +195 -0
195 lines not on this page · raw message
Signature · 1 line
2.21.0
Randy Dunlap
reviewerQuoted 1 line · Jonathan Corbet
+ git merge v5.2-rc1^0
That line is presented in my email client (Thunderbird) as
git merge v5.2-rc1{superscript 0}Could you escape/quote it to prevent that?
Quoted 4 lines
Documentation/maintainer/repo-hygiene.rst new file +4
-0+ +The "^0" will cause Git to do a fast-forward merge (which should be +possible in this situation), thus avoiding the addition of a spurious merge +commit.
Signature · 1 line
~Randy
Jonathan Corbet
maintainerQuoted 8 lines · On Thu, 30 May 2019 17:45:23 -0700 Randy Dunlap <[email protected]> wrote:
Quoted 1 line · Jonathan Corbet
+ git merge v5.2-rc1^0
That line is presented in my email client (Thunderbird) as
git merge v5.2-rc1{superscript 0}Could you escape/quote it to prevent that?
So I'm a wee bit confused. That's a literal string that one needs to type to obtain the needed effect; if thunderbird is doing weird things with it, I think that the problem does not lie with the document...? What change would you have me make here?
Thanks,
jon
Randy Dunlap
reviewerQuoted 8 lines · Jonathan Corbet
Quoted 5 lines · On Thu, 30 May 2019 17:45:23 -0700 Randy Dunlap <[email protected]> wrote:
Quoted 1 line · Jonathan Corbet
+ git merge v5.2-rc1^0
That line is presented in my email client (Thunderbird) as
Quoted 8 lines
Quoted 3 lines
git merge v5.2-rc1{superscript 0}Could you escape/quote it to prevent that?
So I'm a wee bit confused. That's a literal string that one needs to type to obtain the needed effect; if thunderbird is doing weird things with it, I think that the problem does not lie with the document...? What change would you have me make here?
I dunno. I just won't depend on my email client.
I'll read it some other way (like a text editor).
cheers.
Signature · 1 line
~Randy
Quoted 3 lines · Jonathan Corbet
This is a first attempt at following through on last month's discussion about common merging and rebasing errors.
Looks good to me,
Linus
Quoted 7 lines · Jonathan Corbet
docs: Add a document on repository management
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.
Signed-off-by Jonathan Corbet <[email protected]>
We're in the process of defining the pros and cons of merging vs rebasing as part of our workflows internally and this is a great doc that does that with less words and more clarity than I did it, so very happy to add
Documentation/maintainer/repo-hygiene.rst line 31
Quoted 10 lines · Jonathan Corbet
Documentation/maintainer/repo-hygiene.rst new file +10
-0+Rebasing +======== + +"Rebasing" is the process of changing the history of a series of commits +within a repository. At its simplest, a rebase could change the starting +point of a patch series from one point to another. Other uses include +fixing (or deleting) broken commits, adding tags to commits, or changing +the order in which commits are applied. Used properly, rebasing can yield +a cleaner and clearer development history; used improperly, it can obscure +that history and introduce bugs.
Rebasing is being used in two senses here. The first is where the diffs don't change (much), but the starting point of the changes is being changed. The second is where a broken commit is dropped, adding a signed-off-by, etc.
Both have the property that they can used for good or ill, but the details when this is an issue can change a bit. More below...
Documentation/maintainer/repo-hygiene.rst line 40
Quoted 8 lines
Documentation/maintainer/repo-hygiene.rst new file +8
-0+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 not be rebased. Others may have pulled a copy of your tree and + built on it; rebasing 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 seems to be a bit too categorical. It's been recommended, and some people do, push patches to a branch so the zero-day bot will pick it up and test for potential problems. And broken commits *do* get dropped from candidate stable kernel releases. And, of course, there's linux-next, which is constantly getting rebased.
And there have been people who have pushed out RFC patche series onto a git branch, and publicized it on LKML for the convenience of reviewers. (Perhaps because there is a patch which is so big it exceeds the LKML size restrictions.)
I think it's more about whether people know that a branch is considered unstable from a historical perspective or not. No one builds on top of linux-next because, well, that would be silly.
Finally, I'm bit concerned about anything which states absolutes, because there are people who tend to be real stickler for the rules, and if they see something stated in absolute terms, they fail to understand that there are exceptions that are well understood, and in use for years before the existence of the document which is trying to codify best practices.
Documentation/maintainer/repo-hygiene.rst line 60
Quoted 4 lines
+ - Realize the rebasing a patch series changes the environment in which it
Documentation/maintainer/repo-hygiene.rst new file +3
-0+ was developed and, likely, invalidates much of the testing that was + done. A rebased patch series should, as a general rule, be treated like + new code and retested from the beginning.
In this paragraph, "rebasing" is being used in the change the base commit on top of which a series of changes were based upon. And it's what most people think of when they see the word "rebase".
However "git rebase" is also used to rewrite git history when dropping a bad commit, or fixing things so the branch is bisectable, etc. But in the definitions above, the word "rebase" was defined to include both "changing the base of a patch stack", and "rewriting git history". I wonder if that helps more than it hinders understanding.
At least in my mind, "rebasing" is much more often the wrong thing, where as "rewriting git history" for a leaf repository can be more often justifable. And of course, if someone is working on a feature for which the review and development cycle takes several kernel releases, I'd claim that "rebasing" in that case always makes sense, even if they *have* exposed their patch series via git for review / commenting purposes.
Regards,
- Ted
Jonathan Corbet
maintainerQuoted 6 lines · On Sat, 1 Jun 2019 11:42:48 -0400 "Theodore Ts'o" <[email protected]> wrote:
Finally, I'm bit concerned about anything which states absolutes, because there are people who tend to be real stickler for the rules, and if they see something stated in absolute terms, they fail to understand that there are exceptions that are well understood, and in use for years before the existence of the document which is trying to codify best practices.
Hence the "there are exceptions" text at the bottom of the document :)
Anyway, I'll rework it to try to take your comments into account. Maybe we should consistently say "rebasing" for changing the parent commit of a patch set, and "history modification" for the other tricks...?
Thanks for taking a look,
jon
Hi Jon,
Quoted 9 lines · Jonathan Corbet
Quoted 6 lines · On Sat, 1 Jun 2019 11:42:48 -0400 "Theodore Ts'o" <[email protected]> wrote:
Finally, I'm bit concerned about anything which states absolutes, because there are people who tend to be real stickler for the rules, and if they see something stated in absolute terms, they fail to understand that there are exceptions that are well understood, and in use for years before the existence of the document which is trying to codify best practices.
Quoted 5 lines
Hence the "there are exceptions" text at the bottom of the document :)
Anyway, I'll rework it to try to take your comments into account. Maybe we should consistently say "rebasing" for changing the parent commit of a patch set, and "history modification" for the other tricks...?
Or just "reworking a branch" for the other tricks?
Gr{oetje,eeting}s,
Geert
Signature · 5 lines
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected] In personal conversations with technical people, I call myself a hacker. But when I'm talking to journalists I just say "programmer" or something like that. -- Linus Torvalds
Quoted 10 lines · Jonathan Corbet
Quoted 6 lines · On Sat, 1 Jun 2019 11:42:48 -0400 "Theodore Ts'o" <[email protected]> wrote:
Finally, I'm bit concerned about anything which states absolutes, because there are people who tend to be real stickler for the rules, and if they see something stated in absolute terms, they fail to understand that there are exceptions that are well understood, and in use for years before the existence of the document which is trying to codify best practices.
Quoted 5 lines
Hence the "there are exceptions" text at the bottom of the document :)
Anyway, I'll rework it to try to take your comments into account. Maybe we should consistently say "rebasing" for changing the parent commit of a patch set, and "history modification" for the other tricks...?
Those names sound good to me. Thanks!!
- Ted
Hi Jon,
Quoted 10 lines · Jonathan Corbet
This is a first attempt at following through on last month's discussion about common merging and rebasing errors. The hope here is to document existing best practices rather than trying to define new ones. I've certainly failed somewhere along the way; please set me straight and I'll try to do better next time.
Thanks,
jon
Quoted 8 lines
-------------
docs: Add a document on repository managementEvery 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.
Signed-off-by Jonathan Corbet <[email protected]>
Thanks!
Documentation/maintainer/repo-hygiene.rst line 19
Quoted 8 lines
Documentation/maintainer/repo-hygiene.rst new file +5
-0+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 results from a desire to avoid merges, while others come from
result
Quoted 1 line
+merging a little too often.
[...]
Quoted 1 line
+ - Realize the rebasing a patch series changes the environment in which it
Realize that
Quoted 9 lines
Documentation/maintainer/repo-hygiene.rst new file +8
-0+ was developed and, likely, invalidates much of the testing that was + done. A rebased patch series should, as a general rule, be treated like + new code and retested from the beginning. +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
Documentation/maintainer/repo-hygiene.rst line 189
Quoted 10 lines
Documentation/maintainer/repo-hygiene.rst new file +10
-0+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 v5.2-rc1^0 + +The "^0" will cause Git to do a fast-forward merge (which should be +possible in this situation), thus avoiding the addition of a spurious merge +commit.
I usually use
git rebase v5.2-rc1 <mybranch>
_after_ verifying everything has been merged, i.e.
git cherry -v v5.2-rc1 <mybranch>
did not give any output.
Gr{oetje,eeting}s,
Geert
Signature · 5 lines
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected] In personal conversations with technical people, I call myself a hacker. But when I'm talking to journalists I just say "programmer" or something like that. -- Linus Torvalds