Re: [PATCH] technical doc: add a design doc for the evolve command

>
> On 11/14/2018 7:55 PM, sxenos@google.com wrote:
> > From: Stefan Xenos <sxenos@google.com>
> >
> > This document describes what an obsolescence graph for
> > git would look like, the behavior of the evolve command,
> > and the changes planned for other commands.
>
> Thanks for putting this together!
>
> > diff --git a/Documentation/technical/evolve.txt b/Documentation/technical/evolve.txt
> ...
> > +Git Obsolescence Graph
> > +======================
> > +
> > +Objective
> > +---------
> > +Track the edits to a commit over time in an obsolescence graph.
>
> The file name and the title are in a mismatch.
>
> I'd prefer if the title was "Git Evolve Design Document" and this
> opening paragraph
> was about the reasons we want a 'git evolve' command. Here is my attempt:
>
>    The proposed 'git evolve' command will help users craft a
> high-quality commit
>    history in their topic branches. By working to improve commits one at
> a time,
>    then running 'git evolve', users can rewrite recent history with more
> options
>    than interactive rebase. The core benefit is that users can pause
> their progress
>    and move to other branches before returning to where they left off.
> Users can
>    also share progress with others using standard 'push', 'fetch', and
> 'format-patch'
>    commands.
>
> > +Background
> > +----------
>
> Perhaps you can call this "Example"?
>
> > +Imagine you have three dependent changes up for review and you receive feedback
> > +that requires editing all three changes. While you're editing one, more feedback
> > +arrives on one of the others. What do you do?
>
> "three dependent changes" sounds a bit vague enough to me to possibly
> confuse readers. Perhaps
> "three sequential patches"?
>
> > +- Users can view the history of a commit directly (the sequence of amends and
> > +  rebases it has undergone, orthogonal to the history of the branch it is on).
>
> "the history of a commit" doesn't semantically work, as a commit is an
> immutable Git object.
>
> Instead, I would try to use the term "patch" to describe a change to the
> codebase, and that
> takes the form as a list of commits that are improving on each other
> (but don't actually
> have each other in their commit history). This means that the lifetime
> of a patch is described
> by the commits that are amended or rebased.
>
> > +- By pushing and pulling the obsolescence graph, users can collaborate more
> > +  easily on changes-in-progress. This is better than pushing and pulling the
> > +  changes themselves since the obsolescence graph can be used to locate a more
> > +  specific merge base, allowing for better merges between different versions of
> > +  the same change.
>
> (Making a note so I come back to this. I hope to learn what you mean by
> this "more specific
> merge base".)
>
> > +
> > +Similar technologies
> > +--------------------
> > ... It can't handle the case where you have
> > +multiple changes sharing the same parent when that parent needs to be rebased
>
> Perhaps this could be made more concrete by describing commit history
> and a specific workflow
> change using 'git evolve'.
>
> Suppose we have two topic branches, topic1 and topic2, that point to
> commits A and B,
> respectively.Suppose further that A and B have a common parent C with
> parent D. If we rebase
> topic1 relativeto D, then we create new commits C' and A' that are newer
> versions of commits
> C and A. It would benice to easily update topic2 to be on a new commit
> B' with parent C'.
> Currently, a user needs to knowthat C updated to C', and use 'git rebase
> --onto C' C topic2'.
> Instead, if we have a marker showing thatC' is an updated version of C,
> 'git log topic2'
> would show that topic2 can be updated, and the 'gitevolve' command would
> perform the correct
> action to make B' with parent C'.
>
> (This paragraph above is an example of "what can happen now is
> complicated and demands that
> the user keep some information in their memory" and "the new workflow is
> simpler and helps
> users make the right decision". I think we could use more of these at
> the start to sell the
> idea.)
>
>
> > +and won't let you collaborate with others on resolving a complicated interactive
> > +rebase.
>
> In the same sentence, we have an even more complicated workflow
> mentioned as an aside. This
> could be fleshed out more concretely. It could help describing that the
> current model is for
> usersto share "!fixup" commits and then one performs an interactive
> rebase to apply those
> fixups inthe correct order. If a user instead shares an amended commit,
> then we are in a
> difficult state toapply those changes. The new workflow would be to
> share amended commits
> and 'git evolve'inserts the correct amended commits in the right order.
>
> I'm a big proponent of the teaching philosophy of "examples first". It's
> easier to talk
> abstractlyafter going through some concrete examples.
>
> >   You can think of rebase -i as a top-down approach and the evolve command
> > +as the bottom-up approach to the same problem.
>
> This comparison is important. Perhaps it is more specific to say
> "interactive rebase splits
> a plan torewrite history into independent units of work, while evolve
> collects independent
> units of workinto a plan to rewrite history."
>
> > +
> > +Several patch queue managers have been built on top of git...
> > +
> > +Replacements (refs/replace) are superficially...
>
> These two paragraphs could be moved lower, under a "Semi-Related Work"
> section,
> because they describe things that are a bit similar, but are unable to
> help us solve the
> problem at hand.
>
> > +
> > +Goals
> > +-----
> > +Legend: Goals marked with P0 are required. Goals marked with Pn should be
> > +attempted unless they interfere with goals marked with Pn-1.
>
> I like the prioritization here.
>
> > +P0. Any commit that may be involved in a future evolve command should not be
> > +    garbage collected.
>
> I wonder about the priority here. If we GC'd commit A but still have the
> newer A', I can
> either thinkthat
>
> 1. We will no longer need to run 'git evolve', or
> 2. We run 'git evolve' on something that can reach A', but A' already
> contains all the
>     informationwe need to produce a "final" commit A''.
>
> I apologize that I'm not able to read the whole thing right now, and I
> will pick up reading
> from here again soon. Hopefully the feedback above is constructive in
> the mean time.
>
> Thanks,
> -Stolee