Re: Remaining Merge Tracking auditing features for 1.5

On Mon, 02 Jul 2007, Mark Phippard wrote:

> On 7/2/07, Karl Fogel <kfogel@red-bean.com> wrote:
> >Daniel Rall <dlr@collab.net> writes:
> >> While this functionality could be delivered by piggy-backing on
> >> existing sub-commands ('svn log' and 'svn info' have been considered
> >> at length), discussion leads me to believe that we might be better off
> >> introducing a new sub-command to deliver these features:
> >>
> >> svn mergeinfo --available-from=URL TARGET[@REV]
> >> svn mergeinfo [-r ARG] [--merged-from | --merged-to] TARGET[@REV]
> >
> >"--available-from" is a synonym for "--unmerged-from", right?
> >
> >By the way, why don't URL take an @REV qualifier in the first example?
> >If the --merged-from target in the second example can take @REV, I
> >would have though URL in the first example could too.
>
> I think it does, and he was just simplifying it.

Yup, it'd allow the @REV qualifier.

> >I'm not sure what the semantics of the "-r ARG" are.
>
> It probably applies more to --merged-to, but it would be saying where
> has this been revision been merged? Imagine, you make wanted to what
> branches that the BDB repository corruption fix had been merged to.
>
> You can get the --merged-from for a single revision using svn diff,
> but this is a more convenient option and adds some symmetry.

The "-r" option is intended to help locate where a revision or set of
revisions has been merged to within the repository. As Mark suggests,
it applies to the "--merged-to" and "--merge-from" options, to fulfill
the "Find Change Set" requirement (by revision and/or path)
<http://subversion.tigris.org/merge-tracking/requirements.html#auditing>.

I was dubious of the best way to express this revision query UI, but
jammed it into "-r", since I figured doing so would at least produce
some lively discussion. ;-) Can you suggest a better UI for this?

> >> The output of "Change Set Merge Availability" will look like that of
> >> 'svn log'. The semantics will be slightly different, listing logs
> >> from URL instead of from TARGET.
> >
> >Have we considered piggy-backing on 'svn merge' itself?
> >
> > 1. svn merge --info-unmerged FROM_URL TARGET[@REV]
> > 2. svn merge --info-merged-from TARGET[@REV]
> > 3. svn merge --info-merged-to TARGET[@REV]
> >
> >In fact, even if the subcommand were "mergeinfo", I would still like
> >to offer the above option structure for consideration.
>
> I made a similar proposal. Dan did not like it. I imagine it is
> because it is asking a command to do something completely different.
> It would almost be like asking commit or update to show log
> information. I will let Dan provide more reasons.

I certainly considered piggy-backing on 'svn merge'. But as someone
-- C-Mike, I think -- pointed at the last CollabNet engineering
offsite, doing so significantly changes the semantics of the 'merge'
sub-command based on the options its passed.

We're not talking about change in behavior that could even really be
expressed as modal a here, either -- the type of operation we're
getting would be completely different, no longer having anything to do
with how users know 'merge' today. The best argument is that the new
operation is "related to merge meta data, useful before/after a
merge", a classification not strictly in tune with the merge operation
itself.

The closest comparision we have in the command-line application today
is 'diff --summarize', which is at least still producing diff output,
even if the output format is so different that it arguably should've
been a separate sub-command. Alternately, you could consider
'switch --relocate', which is again at least doing some switch-like
behavior, and again could arguably have been its own sub-command.

As noted in the first email Mark linked to
<http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=127104>,
if we wanted to piggy-back on existing sub-commands, the
"--merged-from" and "--merged-to" options might be more appropriate
hung off of the 'info' sub-command (likely accepting a revision range
argument). The "--available-from" option might be hung off of the
'log' sub-command.

> >> The output of "Find Change Set" will include merging revision, URL,
> >> and range list:
> >>
> >> $ svn mergeinfo --merged-to /trunk
> >> At r14, merged r3-7, r13 from /branches/featureX to /trunk
> >> At r60, merged r30-57 from /branches/featureY to /trunk
> >
> >For a moment I almost proposed "r30-r57", but I guess that takes up
> >too much horizontal space (and is completely idiosyncratic).
>
> I think we went through this when discussing sussman's output for
> notifications and settled on the format Dan is proposing.

I want to stay consistent with Ben's 'merge' output, which actually
looks a little different than what I stuck in the proposal:

  $ svn merge -r 25585:25587 https://svn.collab.net/repos/svn/trunk
  --- Merging r25586 through r25587:
  U subversion/libsvn_wc/adm_ops.c
  C subversion/tests/cmdline/revert_tests.py

> >> $ svn mergeinfo --merged-from /branches/featureX
> >> At r14, merged r3-7, r13 from /branches/featureX to /trunk
> >>
> >> $ svn mergeinfo --merged-to -r37
> >> At r60, merged r30-57 from /branches/featureY to /trunk
...
> >> $ svn mergeinfo --merged-to -r37 /trunk
> >> At r60, merged r30-57 from /branches/featureY to /trunk
...
> >In real life, these lines are very often going to overflow 80 columns.
> >Perhaps we should declare now (for parsers) that whitespace at the
> >beginning of a line means a continuation line, and format like this...
> >
> > $ svn mergeinfo --merged-from /branches/featureX
> > At r14, merged r3-7, r13
> > from /branches/featureX
> > to /trunk
> > $
>
> I like that idea.

+1. We need to stay machine parsable (as also stated by Giovanni). I
was focusing more on the content than the output format.

That said, we do have --xml mode now for machine parsing, so I
wouldn't want to take that so far it impacted day-to-day usability.

...
> >> The only other viable alternative would be to introduce multiple new
> >> sub-commands: one to handle the path/revs output by
> >> --merged-from/--merged-to, and another to handle the 'log'-style
> >> output from --available-from. This offers the benefit of consistent
> >> output from a sub-command regardless of the options it's passed
> >> (arguably similar to the modal behavior of --xml), but has the obvious
> >> down-side of introducing yet more sub-commands that a user must wrap
> >> their head around.
...

Karl, you know I'm completely open to other options. :-)
I'm more than a little too close to this problem (Merge Tracking), at
this point. The wall I keep banging my head into is certainly getting
in the way of my vision.

> For example, neither of us love the idea of overloading this command
> and also providing different output formats, but somehow it felt
> better than overloading a long existing command (log), overloading and
> changing the output of a long existing command (info) or completelty
> re-purposing an existing command (merge). We also know that there is
> a lot of rightful resistance to adding sub-commands, so we tried to
> limit this to just one.

That said, I do like the split suggested by Giovanni:

  svn mergeinfo [-r ARG] [--merged-from | --merged-to] TARGET[@REV]
  svn mergeavail [--from URL[@REV]] TARGET[@REV]

And, the suggested sub-command naming style does include the "merge"
prefix, which I think Karl like as a visual UI cue for users.

> Here are some links to past discussions on some of the alternatives:
>
> http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=127104
> http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=127603

I'd really appreciate some more feedback on this or the previous
threads. I've been banging my head into a wall on this one for a
while now without making much progress. Comparison to other VC/SCM
systems would be quite helpful, too.