Skip to contentSkip to conversation

Rough draft document on merging and rebasing

RFC PATCH In review Jonathan Corbet 6 participants 11 messages May 30, 2019 – Jun 4, 2019

Subsystems (2)
lore
Share & tools
lore

Jonathan Corbet

author maintainer
#0 lore raw

RFC 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
index 2a14916930cb..48c1d56253d8 100644
@@ -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
reviewer
#1 lore raw
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?

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
author maintainer
#2 lore raw
Quoted 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

reviewer
#3 lore raw
Quoted 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
Acked-by on v1 1/1
#5 lore raw
In reply to Jonathan Corbet
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.

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

#6 lore raw
In reply to Jonathan Corbet

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

author maintainer
#7 lore raw
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.

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

#8 lore raw

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
#9 lore raw
In reply to Jonathan Corbet
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

#10 lore raw
In reply to Jonathan Corbet

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 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.

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