Hi Clay, you are right, for TRUNK, there is no need to set a specific peg revision. That should be done for TAGs. Note that with tools like Tortoise SVN (win only) the interface gives options to directly set peg revs.
2013/6/6 Clay Leeds <[email protected]> > 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 > > -- pascal
