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

From: Thomas Rast <trast@student.ethz.ch>
Date: Sep 11, 2008, 15:38 UTC
Message-ID: <1221147525-5589-1-git-send-email-trast@student.ethz.ch>
In-Reply-To: <200809030738.09589.trast@student.ethz.ch>

So here's the follow-up I promised.

Junio C Hamano <gitster@pobox.com> wrote:

Show 11 quoted lines

>
> Thomas Rast <trast@student.ethz.ch> writes:
> > - 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:

Show 14 quoted lines

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