Issue #2820 - Clarifications and input needed

I'm trying to look into issue #2820, and just want to run some ideas past
folks. According to the issue, requirements and func-spec can be found in
the following places:

http://subversion.tigris.org/merge-tracking/requirements.html#change-set-availability
http://subversion.tigris.org/merge-tracking/func-spec.html#show-changesets-available

Thinking purely of APIs, and addressing the list requirements (repeated
below for your convenience), here are my first thoughts on the implementation:

> Show Changesets Available for Merge
>
> Support query of any path (file, directory, or symlink) to find out
> what changes (revisions) for a merge source haven't been merged under
> it. For files, "under" just means "into".

The algorithm:

1. Parse the mergeinfo of PATH@REV into a list of sources and revision
   ranges.

2. If a particular merge source of interest is provided (I'm assuming
   the question "what changes for *any* previous merge source haven't
   been merged?" is interesting, too), ignore other sources.

3. For each source of interest, get the source's whole range of history,
   subtract out the revisions already merged, and return the rest.

Something like:

/* Set SOURCES_AND_RANGES to a hash mapping const char * source URLs to
   an apr_array_header_t * list of svn_merge_range_t * revision ranges
   which represents merge sources and corresponding revision ranges not
   yet merged into PATH_OR_URL@PEG_REVISION.

   The returned information is limited to the set of merge sources already
   represented in mergeinfo stored on PATH_OR_URL@PEG_REVISION, filtered
   by the selection of a particular merge SOURCE URL of interest (which
   may be NULL).

   Use POOL for all necessary allocations.
*/
svn_client_mergeinfo_unmerged(apr_hash_t **sources_and_ranges,
                              const char *path_or_url,
                              svn_opt_revision_t *peg_revision,
                              const char *source,
                              apr_pool_t *pool)

> Show Changesets Already Merged
>
> Support query any path (file, directory, or symlink) to find out what
> changes (revisions) have been merged under it. For files, "under" just
> means "into".

This is just like the previous thing, except we don't have to consult
anything except the mergeinfo itself (no history lookups, no revision range
mathematics):

/* Set SOURCES_AND_RANGES to a hash mapping const char * source URLs to
   an apr_array_header_t * list of svn_merge_range_t * revision ranges
   which represents merge sources and corresponding revision ranges
   merged into PATH_OR_URL@PEG_REVISION.

   The returned information is limited to the set of merge sources already
   represented in mergeinfo stored on PATH_OR_URL@PEG_REVISION, filtered
   by the selection of a particular merge SOURCE URL of interest (which
   may be NULL).

   Use POOL for all necessary allocations.
*/
svn_client_mergeinfo_merged(apr_hash_t **sources_and_ranges,
                            const char *path_or_url,
                            svn_opt_revision_t *peg_revision,
                            const char *source,
                            apr_pool_t *pool)

> Show Changesets Blocked from Merging
>
> If you've blocked some set of revisions from being merged from branch
> B into some destination (e.g. trunk), you should be able to discover
> which revisions have been blocked.

I don't really grok how blocked changesets are represented. I guess I
thought they were just merge sources about which you lied about merging them
(claiming you did when you didn't). What's the scoop?

Also, now that I've finished typing the above, I'm wondering how these APIs
deal with recursion and children of directories which have differing
mergeinfo than their parents. Does the API not care, and calling program
handle recursing and such? Does the API take a depth flag and move to a
callback model (one call per unique set of things to report)? Since files
and directories could have come into existence at different times, does this
mean we've got to do expensive history lookups for each individual item? Am
I so completely off-base with the ideas behind these APIs answering these
questions would be more costly than just whacking me with a clue stick?

Help?

-- 
C. Michael Pilato <cmpilato@collab.net>
CollabNet   <>   www.collab.net   <>   Distributed Development On Demand