[RFC] history editing vs history presentation

[Jonathan Lange]

On Tue, Jun 9, 2009 at 4:12 PM, Robert
Collins<robert.collins at canonical.com> wrote:
> So, I wanted to make several different RFC's to get discussion going
> about this. But I think the issues are not sufficiently teased out yet.
> In part, I hope to tease out the issues here and perhaps end up with
> some suggestions about what we should aim to have to provide a good mix
> of effective tools.
>

Thanks for this RFC -- it's a great analysis of the problem domain.

[...]
> History editing
> +++++++++++++++
>
> Sometimes, at arbitrary times after something is committed to history,
> users realise they want a variation of the content and history that
> can't be achieved by simply appending a corrective change to the end.
>
[...]
>
> One of the key side effects of history editing is that edited history
> cannot be trivially merged from: it acts as a brand new creation.
>
> Some motivations for this turn up frequently:
>
> Splitting or joining code
> -------------------------
>
> VCS systems require users to make fairly arbitrary divisions between
> code they manage, and code that isn't managed. Often users make
> decisions that later experience shows would be better made differently.
>

For example, taking a project managed as one tree/branch and splitting
it into two distinct projects?

> A subset of the changes introduced are wanted - e.g. a slice of some
> sort through time. This sort of edit is sometimes very simple, and
> sometimes very complex - consider detangling a library which was in a
> subdir but wasn't perfectly isolated. Joining code is similar but in
> reverse. Note that doing a merge between two projects to get their
> history to join is not the same thing as editing the history so they
> appear to have had a single origin: In the latter case you end up with
> one history root, whereas in the former case you have two and there is
> no clear version of the subproject to use at any given point in the
> upper project.
>

FWIW, I had to read these two paragraphs a couple of times to figure
out what was meant.

[...]
> What context are what edits needed in?
> ++++++++++++++++++++++++++++++++++++++
>
> So we have three broad sets of edits:
> a)splitting/joining
> b)tweaking
> c)polishing
> d)cherrypicking
>
> And three main states that a given part of history can be in:
> 1)released
> 2)integrated
> 3)pending-integration
>
> I think that collaboration happens in all three states. Distros
> collaborate around released code (by creating patches to it and pulling
> in select bits of integrated code), project developers collaborate
> around mainly integrated code (by creating patches), and in some
> circumstances - large branches, risky changes, big projects - subsets of
> project developers will collaborate on pending-integration code.
>
> ' ' - relatively little or no use
> '.' - some use
> 'X' - relatively frequent use
>
> [Data for the below needed, ways of getting it solicited]
> Frequency of need for history editing based on state of code:
>  abcd
> 1X. X
> 2...X
> 3 .X.
>

This makes sense to me (after I switched to a fixed-width font).

[...]
> Existing bzr facilities
> +++++++++++++++++++++++
>
> This document has tried to layout some terms for talking about the
> operations that are possible in high level terms without bogging down in
> the precise capabilities of current tools. But its useful to see what
> bzr currently offers
>
> bzr has no builtin or readily available facility for splitting/joining
> of history. [See the topic for details on why 'bzr join' does not
> count.]
>
> bzr has no mechanism for performing tweak-edits either.
>
> bzr has a rebase plugin that can perform automated replays (a series of
> cherrypicks).
>
> The bzr-loom plugin provides some patch management facilities *for
> multiple developers editing the same patches* without doing history
> editing, but doesn't offer a complete set of polishing primitives,
> limiting its usefulness. A good set of history polishing tools built
> into the core of bzr wouldn't eradicate bzr-loom, but they would mean
> that loom is much less needed for the very common case of a single
> developer polishing their own submissions.
>
> A call to arms
> ++++++++++++++
>
> The default bzr facilities should be enough to remove the current
> cognitive dissonance contributors have: they think in terms of patches,
> but bzr works in terms of tree states.
>
> To do this, we should build up a complete set of history editing tools -
> in particular the patch management primitives. We should make sure that
> they have clear warnings, refuse to operate on released or integrated
> code without overrides, and are easy and robust.
>
> And then the default work area bzr provides should be extended to have
> enough tracking data to make working on patches wonderful again.
> bzr-loom demonstrates one possible mode - making that fantastic for
> single developers and only slightly more complex for developers
> collaborating on the same patches is one approach that would leverage a
> bunch of existing work. However, bzr-loom would need its UI to be made
> more 'thread'(patch) centric than it is to achieve this What we need to
> ensure though, is that we aim for having one system that scales from
> single developer editing their own patches, up to a group of folk
> editing a set of patches - which the landing of brisbane core would have
> been massively improved by.
>

Agreed.

As far as I can tell, this won't actually address the split/join,
tweaking or cherrypicking cases, only the polishing case -- is that
right? If so, what do you think we should do to address the other
three cases?

I personally would love to see a patch-centric loom-like feature in
Bazaar core. The principles you describe (clear warnings, one system
that scales from single developer to multiple folk, etc) are the right
ones, I think, but they are only a starting point. This RFC doesn't
say what such a feature would actually look like or how it would
work.[1]

What should it look like? How would it work? What do we have to do to
get this wonderful new UI?

jml

[1]  I'm guessing you wanted to limit the scope of an already hefty document :)