Hi Clay,
Many thanks for looking into this. Whilst I can't offer an opinion on
one solution or the other, I do know this is a problem we need to solve.
So I'm +1 for your recommendation.
The only technical point I would make is that SVN 1.5 is quite old now.
We've been using SVN 1.7 for over a year now. Therefore I wouldn't worry
about remaining 1.5 compatible, especially given the limitations imposed
by 1.5.
Thanks,
Chris
On 06/06/2013 06:25, Clay Leeds wrote:
Hi folks,
I hope you're well!
I've been investigating how to get our documentation into our Source & Binary
RELEASEs without requiring the duplicate work of trying to maintain two sets of
documentation. I noticed the 'advertisement' from Infra@ plugging their willingness
to help projects, and so I reached out, and they recommended `svn:externals`.
Before I proceed, I'd like to get your input on how we should proceed, or if
anyone has a 'better' idea. I'm leaning toward including the source MarkDown in
the distribution via `svn:externals`, perhaps with a README file pointing at
the web for better rendering of the docs.
Here's a link that discusses including common code in an SVN project:
http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-howto-common-projects.html#tsvn-howto-common-externals
That page has three recommendations:
1. Use svn:externals
2. Use a nested working copy
3. Use a relative location
I won't get into the details on those three recommendations, and I'm sure there
are other solutions, but `svn:externals` seems logical and simple. The other
two aren't appropriate for one reason or another.
In a nutshell, we'd effectively `svn include` the documentation into the
respective repos by setting an svn property like this:
=== SAMPLE - BATIK ===
$ svn propget svn:externals batik
documentation/
//svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/batik/
===
=== SAMPLE - COMMONS ===
$ svn propget svn:externals commons
documentation/
//svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/commons/
===
=== SAMPLE - FOP ===
$ svn propget svn:externals fop
documentation/
//svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/fop/
===
NOTES:
- the above use RELATIVE TO SCHEME PATHS, which require Subversion 1.5+… ABSOLUTE
URLs are the Subversion pre-1.5 alternative, which causes issues when switching
between HTTP & HTTPS
- We can't use `svn:externals` for the parent XML Graphics Project, since it is
also the parent for Batik, Commons & FOP docs, unless we tie it to specific
files (which requires Subversion 1.6+).
There are other Subversion 1.5+ options for specifying the `svn:externals` PATH
(e.g., using RELATIVE or ABSOLUTE paths since their on the same system), but
I'm not convinced of the benefits:
=== SAMPLE - BATIK (ABSOLUTE URL - Subversion pre-1.5) ===
$ svn propget svn:externals batik
documentation/
http://svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/batik/
===
=== SAMPLE - BATIK (ABSOLUTE PATH - Subversion 1.5+) ===
$ svn propget svn:externals batik
documentation/ /repos/asf/xmlgraphics/site/trunk/content/batik/
===
=== SAMPLE - BATIK (RELATIVE PATH - Subversion 1.5+) ===
$ svn propget svn:externals batik
documentation/ ../site/trunk/content/batik/
===
=== SAMPLE - BATIK (RELATIVE TO SCHEME - useful for those accessing via HTTP or
HTTPS - Subversion 1.5+) ===
$ svn propget svn:externals batik
documentation/
//svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/batik/
===
There is a recommendation that specific revisions are used for `svn:externals`,
which helps when you don't have control over the other system. I don't think
this is necessary or helpful for TRUNK, although I wonder how tagged branches
would be affected… It's possible tagged branches would need a revision to
ensure they are STATIC respective to their code/documentation versions. This
may require the added step to the RELEASE process of switching the specific
Documentation Revision to keep it in sync w CODE.
BTW, I did notice that the Batik portion of the documentation is ~330MB. I was
going to start with XML Graphics Commons and see how it worked, before I went
to FOP and eventually Batik...
Warm regards,
Clay
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
