[Svnmerge] Documentation Improvements

[Thomas F. O'Connell]

I'd like to work on improving the svnmerge.py documentation at the
OrcaWare SubversionWiki with a healthy dose of community feedback. I'd
like to expand the number of use cases covered, as well as clarify the
existing use cases.

Here are the use cases that seem to be most common:

1. Initializing bidirectional merging on a fresh branch
2. Initializing bidirectional merging on a locally modified branch

These specific cases aren't directly addressed in the Wiki, and I'm
wondering whether the existing "Quick tutorials" sub-sections,
including "Merging branches back to trunk", could be enhanced to cover
the various larger use cases. For instance, merging branches back to
trunk is different if one has already initialized birectional merging
than if not.

Here are some of my questions about the current documentation:

1. What differs between svnmerge.sh and svnmerge.py initialization? The
two primary other sources of documentation
(<http://kenkinder.com/svnmerge/> and
<http://www.dellroad.org/svnmerge/index>) use a double initialization
technique for bidirectional merging. When I tried that recently with
svnmerge.py, I was warned that initialization had already occurred for
'.' when I went to initialize the branch after already having
initialized the trunk. What are the differences in mechanics between the
two, and what is the best way to initialize bidirectional merging in a
new branch?

2. What does this clause mean in "Merging branches back to trunk"?
"Where XXX-XXX is the list of revisions before the branch was
created..." Wouldn't that be r1-PREV or something similar for
relatively simple development trees? Wouldn't you typically want all
revisions preceding branch creation? What happens if the -r flag isn't
used? And should the second XXX block always be the "revision number in
which the branch was created"?

I'll gladly attempt to address other use cases and clarifications and
suggestions for integrating them if people help me better understand
intended uses and best practices.

Thanks!

--
Thomas F. O'Connell

optimizing modern web applications
: for search engines, for usability, and for performance :

http://o.ptimized.com/
615-260-0005