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

[Derrick Stolee <stolee@gmail.com>]

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