[PATCH 0/2.5] Documentation: new upstream rebase recovery section in git-rebase

So here's the follow-up I promised.

Junio C Hamano [off-list ref] wrote:

Thomas Rast [off-list ref] writes:

quoted

- Is it perhaps too verbose, or in the wrong place?  I did not want to
  detract from the feature descriptions that the manpage should first
  and foremost contain.  Chances that a user will "accidentally" read
  the section at this position and length seem fairly low however.

It feels on a bit too repetitive side, but I think this is going in the
right direction.  How about dropping the earlier part of the change to
Notes section (but keep "See also" which is a good guide for understanding
the said "implications")?

I rewrote it to include the actual rebase behaviour and some scenarios
that arise from 'rebase -i', 'commit --amend' etc., then tried to
shorten the section as far as I could.  Hopefully this cut down on the
repetitions.  Unfortunately it still grew longer due to the extra
content.  The second patch then includes references to that section in
the appropriate manpages.

The third patch is again RFC, and I made it regarding this section:

The additions you made are all about why rebasing public history is bad
from mechanisms [...] POV.
While that description is all good, I think there should also be a
discussion from the patchflow/workflow angle.

"Upstream has rebased" almost implies that it has its own upstream
(i.e. "My upstream" is not the toplevel upstream, but is a subsystem tree
or something).

Rebasing upstream is bad, but an upstream that backmerges from its own
upstream too often is equally bad, and the reason of the badness, viewed
from the workflow angle, shares exactly the same component.

It means that the mid-level upstream in question is not focused enough.

I noticed that there is no manpage in which we document such workflows
anyway.  There is a short definition of 'topic branch' in
glossary-content.txt, and a parenthetical definition in
user-manual.txt in a sort of "linux.git howto".  Nothing longer,
however.

  [I learned what I know from Linus's Google Tech Talk[1], Tv's more
  recent EuroPython talk[2], looking at git.git, and mail such as the
  ones you linked.  I recommended [2] to people who asked about topic
  branches on #git a few times.]

So this is an attempt to make a "workflow reference".  I tried to
strike a balance between "just" a reference (the Rule/Recipe blocks)
and more of a tutorial approach which explains the reasons.  I would
again greatly appreciate comments.

- Thomas


Thomas Rast (2+1):
  Documentation: new upstream rebase recovery section in git-rebase
  Documentation: Refer to git-rebase(1) to warn against rewriting
  Documentation: add manpage about workflows


[1] http://video.google.com/videoplay?docid=-2199332044603874737
[2] http://blip.tv/file/1114793/