Auditing Design - v1 (was: Re: [merge-tracking] 'svn blame' auditing)

Hyrum K. Wright wrote:
...
> I've decided to investigate what needs to be done to implement 'svn
> blame' auditing support. For those unfamiliar with the problem, the use
> case is simple. Quoting [1]: "If you merge rN into a branch B, and rN
> was committed by author A, then svn blame should show the changed lines
> in B as last touched by A, even if the merge was committed by you and
> you are not A. This must also work when merging a range of revisions
> with different authors."

Thanks to all those who have commented on this thread so far. This
document is a preliminary attempt to incorporate those comments into a
cohesive design. Comprehensive review and suggestions are encouraged.

            Merge Tracking Commutative Author Reporting
                                 or
                       "How to pass the buck"

The Problem
-----------
With the advent of merge tracking, users want the ability to obtain
usable information about with revisions have been merged to a given
location, where a given revision has been merged to, and who the
original author of content within a file is. Collectively, these
reporting operations are referred to as "Merge Auditing".

This design seeks to address only the third aspect of auditing:
reporting commutative authorship of a file by using 'blame', 'log',
'status --show-updates' and 'info', hereafter referred to as "reporting
commands".

This design does *not* attempt to address auditing in the scope of
merges themselves, determining what has been merged where, or where a
particular version of a file exists in the repository. These are left
as an exercise for the reader. :)

Current Behavior
----------------
Currently, the reporting commands treat a merge just like any other
commit: they report the contents changed in the merge as being modified
in the revision and by the person who performed the merge. While this
is useful, we now have the ability to provide much more information to
the user upon request.

Proposed Behavior
-----------------
To maintain backward compatibility, all the reporting commands will
continue to to behave as they currently do. A '--merge-sensitive' (we
can bikeshed about the name later) command-line switch will be added to
the client to enable the extra merge information requested. This switch
will also work with '--xml' to include the additional merge information
in xml-ized output.

Proposed changes with the '--merge-sensitive' switch are:
'svn log':
The original log message, in the current format, with the addition of a
list of revisions that have been merged into the target. The
'--verbose' flag would output the log information for the merged
revisions as well.
(Question: What is the best way to visually represent all the data
being returned by 'svn log --merge-sensitive'?)

'svn blame':
Two additional columns for each line, one with the original revision
number, and one with the original author of that line. Unlike other
commands, we do not need to worry about multiple source revisions,
because each line can have at most one author.

'svn info':
Add two more pieces of information: 'Last Original Author:' and 'Last
Original Revision:'. Note that these could either be set by a merge to
the node, or a commit to the node. In the latter case, they would be
the same as the 'Last Author' and 'Last Revision'.
(Question: Do we need '--merge-sensitive' to do this? Should the 'Last
Original {Author,Revision}' lines appear if only different from 'Last
{Author, Revision}'?)

'svn status --show-updates':
Add additional columns, reflecting the last original authors and revisions.

Implementation
--------------
Each of the reporting commands, although separate, will need to access
the merge info in a similar way. The implementation will provide a
clean interface, so that all of the client APIs can access the reporting
logic. It is anticipated that most of this logic will live in
libsvn_repos, with appropriate parameters punched back through the RA
layer to the client.

[As the requirements and UI are fleshed out, this section will grow as
needed.]

Outstanding Question(s)
-----------------------
As this design is still preliminary, there are outstanding questions.

* From a UI perspective, how best do we handle multiple source revisions
in a single merge revision? That's potentially *a lot* of data. Do we
only need handle the most recent original revision in a merge?

Miscellany
----------
Although not required as part of the Subversion 1.5 "Merge Tracking"
release, auditing is a significant "nice to have" feature, which many
users will find useful. Once the design is finalized, whatever help
people can contribute toward getting it implemented would be appreciated.

Hopefully, the above design accurately describes the Merge Tracking
Auditing scenario, and the design parameters already agreed upon. It
also asks several questions, which I hope we can iron on-list.

I look forward to comments.

-Hyrum