Mark Phippard wrote:
> On Thu, Mar 27, 2008 at 3:36 PM, C. Michael Pilato <cmpilato_at_collab.net> wrote:
>
>> Okay, let me try to flush my brainstate on this issue.
>>
>> A. Only accept a single TARGET. Everybody seems cool with this. This
>> reduces indentation by one level compared to where we are today. Yay!
>>
>> B. Always show log-style output, honoring both the -q and -v flags as they
>> apply to 'svn log'. This gives us one revision per line (plus some other
>> revision metadata) in -q case, and really useful full data in the -v case,
>> plus that in-between gunk in the -qv case. This forces the output into the
>> realm of needing section dividers, unless we support indentation of the log
>> output. I like this.
>>
>> C. We still support --from-source. But we apparently have decided to
>> support *not* providing a source, we still has us trying to deal with
>> multiple sets of output at once (dividers, indentation, etc.). That reduces
>> the scriptability of the output's one-rev-per-lineness, because now wrappers
>> have to pay attention to these section dividers and maintain state. :-(
>>
>> D. We've discussed not showing both eligible and merged [and blocked] at the
>> same time, but using a switch to say which flavor of output we want. That's
>> cool, because it reduces our indentation/output-sets count again. But I
>> disagree with the idea of making "eligible" the default while still
>> maintaining the subcommand name "mergeinfo" which to me -- admittedly
>> tainted by knowledge of the internals -- means the command will show you
>> information about merges, not about would-be merges that may never come to
>> be. Besides, the claim that "you don't need 'svn mergeinfo' to show actual
>> merges by default because 'svn pget svn:mergeinfo'" is only true when you
>> happen to execute 'svn mergeinfo' on the root of a branch which said
>> svn:mergeinfo property is likely to reside.
>
> I would be fine with any default, or even just requiring the
> --show-revs option always.
Another long monologue from me.
Here is my recommendation, which basically aims to make this a safe and stable
starting point for a feature which can later become more friendly but does not
aim to be particularly friendly in the initial implementation. In fact the
command-line invocation is intentionally a little verbose.
SYNTAX AND EXAMPLE
svn mergeinfo --show-revs=REVTYPE --from-source=SOURCE TARGET
REVTYPE is "merged" or "eligible"
SOURCE is URL[@PEGREV] or WC-PATH
TARGET is URL[@PEGREV] or WC-PATH
$ # Example:
$ svn mergeinfo --show-revs=merged \
--from-source=$REPOS/branches/1.5.x/ trunk-wc/
27
81
243
61565
61566
61567
61568
61569
61570
131072
$ # End of example.
OPTIONS AND OUTPUT FORMAT = no options and trivial format
Some of you know my view. KISS. Only support one target, one revision number
per line, one source, one type of revisions at a time, and no fancy
pretty-printed output. Just print a number per line, no headers, no
indentation, no nothing. And NO DEFAULTS until we're sure they're the right
defaults!
If the user wants to see the log entry for each revision, they can pipe the
output (list of revisions) to "xargs svn log PATH [-q] [-v] [--xml] -r". Even
Windows users can do that sort of thing in a script these days.
If the user wants multiple targets, they can issue multiple commands. If they
want multiple sources, ditto. If they want "all" sources, that's an extension
we can add in v1.6 by turning the "--from-source" command-line "FLAG" into a
command-line "OPTION" (becoming truly optional), as well as implementing any of
these other extensions we're talking about that may become highly desired then
but are of uncertain value now.
If we do these extensions in v1.6, they can have extended output formats
(indentation, dividers, etc.) - and the plain output can remain (compatible
with v1.5) when no such extensions are requested.
If we try to agree on a verbose output now with lots of options and dividers
and indentation, well, we just won't be happy with it in time for v1.5.
Why print individual revisions rather than ranges? There are scenarios where
ranges would be nicer, but those scenarios tend to be the single-developer,
small-scale repository, where everything is simple anyway and the developer
probably doesn't really need the feature. (Eligible revisions are contiguous
numbers because nobody is working on any other branch at all.) When the
repository is big and active, the ranges are usually broken up into single
revisions anyway by commits on other branches/projects, and scriptability of
output becomes more important, and one rev per line makes much more sense.
COMMAND NAME = "svn mergeinfo"
(Skip this section if you're already happy with the name.)
As a command for "show me what changes have/haven't been merged from A to B",
the name "svn mergeinfo" is not ideal. It's a bit vague. There is lots of other
"merge information" that Subversion could potentially show the user besides
these lists. It's named directly after the property that Subversion uses to
store its v1.5 merge info, and there is already talk of augmenting this
property with other properties in future to implement blocking, for example.
Options are: (1) call it "svn mergeinfo"; (2) invent a new name or set of names
or options to existing commands; (3) ditch the command for now and supply it as
an external script instead.
(1) is not too bad or hard to get used to; (2) would take too long now; and I'd
be happy with (3). Supplying an external script would leave us free to choose a
better command name (such as "svn log --mergeable-from=URL" or "svn merge
--dry-run --show-revisions-only" or something) when we know what the common
uses for it are. But, if we really want to, we could always upgrade to a new
and better command-line UI and just keep the old "svn mergeinfo" as a
deprecated command.
We've come far enough down the road of supplying this functionality via the
"svn mergeinfo" command that I strongly suggest we keep that name now, even if
it is not ideal. (We might even want to expand it with more options for
outputting different sorts of merge information, which would perhaps better
justify its name.)
CORRECTNESS AND COMPLETENESS = what does it really mean?
In the above sections I was stating my recommendation. Now I'm asking a question.
Can we say what this command should mean with regard to partial merges - ones
that were applied to a sub-tree?
Let's start with "revisions that have been merged from SOURCE into TARGET". By
SOURCE, we mean the line of history that ends at SOURCE[@PEGREV] and extends
back in time as far as it goes across copies, including sub-trees that were
copied separately. And we're going to list the revision number of each change
that modified SOURCE and is recorded as having been wholly or partially merged
into TARGET (into any part of TARGET's history, in the same way that we
consider SOURCE's history). We're not going to try to identify if a change was
only partially merged in, though, we're just going to mention the change as a
whole revision.
Is that what we mean?
The answer is probably, "We mean what the <so-and-so> API means." That's fine,
as long as it's documented.
When we ask it to list "revisions that are eligible to be merged from SOURCE
into TARGET", what do we mean then?
(a) Every revision that changed SOURCE and has never been applied to TARGET
in any way. (This is the complement of the "merged revisions".)
(b) Every revision that changed SOURCE and at least some part of the change
to SOURCE has never been applied to TARGET.
In either case, we're not going to try to identify if a change was only
partially merged in, we're just going to mention the change as a whole revision.
This time, the answer is probably, "We mean what the 'svn merge' command would
try to do." I guess that would be (b). Again, that's a fine answer as long as
it's documented.
Note that if we were to start to output full "svn log" information, including
the lists of paths affected, then we would likely run into difficulties with it
being entirely misleading to claim that a particular list of paths are affected
by a change, when in fact only some of those paths are affected in the target
branch. All the more reason to keep the output simple.
I hope this means we can quickly put in place something that is useful,
unambiguous, and simple enough to build on later without backward compatibility
hassles.
- Julian
>> If our goal is something that is machine parseable, then the easiest thing
>> for scripts to parse would be:
>> single-target, single-source, single-flavor, one-rev-per-line
>>
>> Anything more adds complications, some more easy to deal with than others.
>> So what can we add that brings value to the user without crossing the line
>> of machine parseability.
>>
>> Moving to log output, we have:
>> single-target, single-source, single-flavor, one-block-of-lines-per-rev
>>
>> That's not so bad. But it still leaves us unable to ask, "What merges have
>> been performed to TARGET from any sources?" The minute we allow multiple
>> sources, the machine parseability takes a hit, and we're doing indentation
>> and section headers.
>
>
> I am still not sure that use case is real. It sounds good, and like
> something you would need, but then when I think of the output it just
> never seems useful to me.
>
>
>> Since most (if not all) of the problems noted in this thread are UI related,
>> not API related...:
>>
>> 1. Should we ditch the 'svn mergeinfo' command and roll this behavior
>> into 'svn log', where we don't have to deal with
>> questions of default behaviors because those are already defined?
>
>
> Somewhere dlr has to be chuckling. We went through all of these
> gyrations last summer if you want to check dev@. It was a lot harder
> to get people to comment back then. Using svn log never felt right
> and you would have to add a lot of new options to the command.
>
>
>> 2. Should we ditch the 'svn mergeinfo' command for 1.5, and just ship
>> the APIs so that TortoiseSVN, Subclipse, and other not-constrained-
>> to-text-output consumers can still do their thing?
>>
>> 2b. Should we provide a bindings script that implements this behavior
>> so 1.5 adopters can get the info, but such that we aren't stuck
>> maintaining the chosen UI?
>>
>> Quite honestly, option 2b is looking pretty great to me right now.
>
>
> As long as the API exists I do not care. Having seen this information
> in a GUI I know that it is useful and it would be nice if the CLI
> could do it. I think we could reach consensus around svn mergeinfo
> and be done with it.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe_at_subversion.tigris.org
For additional commands, e-mail: dev-help_at_subversion.tigris.org
Received on 2008-03-27 23:11:43 CET