#summary Tracking IVOA Document Development in Volute

= Tracking IVOA Document Development in Volute: Ray's Approach = 

== Introduction ==

I've used Volute's SVN repository to author and contribute to a number of IVOA Documents, and I've developed a pattern that I find useful.  SVN works best for plain text files as its easier to see differences between revisions (which is one of the reasons I prefer working in HTML as my source format); however, the pattern described here works for Word/OO-based documents.  With these latter formats, you won't be able see differences, but you can track revisions and make good use of the commit log.  

=== Example Document Projects ===

The following projects best exemplify the process I use: 

   * [https://code.google.com/p/volute/source/browse/#svn%2Ftrunk%2Fprojects%2Fregistry%2FSimpleDALRegExt registry/SimpleDALRegExt]
   * [https://code.google.com/p/volute/source/browse/#svn%2Ftrunk%2Fprojects%2Fregistry%2FStandardsRegExt registry/StandardRegExt]
   * [https://code.google.com/p/volute/source/browse/#svn%2Ftrunk%2Fprojects%2Fregistry%2FVODataService registry/VODataService]

Part of these standards were various XML Schema (.xsd) files; these were versioned as well.  


== SVN Organization ==

The two most important part of the organization are:
   * The [https://code.google.com/p/volute/source/browse/#svn%2Ftrunk%2Fprojects%2Fregistry%2FSimpleDALRegExt main directory] which keeps "under development" versions of the documents where most of the check-ins happen
   * An [https://code.google.com/p/volute/source/browse/#svn%2Ftrunk%2Fprojects%2Fregistry%2FSimpleDALRegExt%2Frc rc] directory which holds "release candidates"--i.e. "tagged", dated versions that get posted to the TWiki and uploaded to the document server.  

I will usually also have a [https://code.google.com/p/volute/source/browse/#svn%2Ftrunk%2Fprojects%2Fregistry%2FSimpleDALRegExt%2Fsamples samples] directory to keep example XML files that are compliant with schema defined in the spec.  I use these to regularly do test validations as the schemas evolve.  

You will notice that the main spec document has a generic name--without dates.  This is so that once I have the directory checked out, I don't have to switch which file I'm editing based on what's been released.  Further, that file can carry along the submit logging across multiple releases.  

That said, I do keep as separate files the versions for the different phases of the document, e.g. `SimpleDALRegExt-wd.html`, `SimpleDALRegExt-pr.html`, and `SimpleDALRegExt-rec.html`.  This is because the transition between the phases is somewhat fuzzy, and I often find myself wanting to work on the version for the new phase while we're still finishing off the last from the old phase.  Since these different files contain substantially different boiler-plate text, it's useful to keep these as separate files.

When it comes time to share a version of the document either on the Twiki or post to the document repository, I update the date on the cover page and copy it to the `rc` directory, changing the file name to the canonical pattern.  You will notice that I also checked in PDF versions into the `rc` directory as well.  Because of a bit of extra work I got to to create a quality PDF from the HTML (e.g. inserting page numbers and setting page breaks), I think it's worth checking in the post-HTML versions.  If the original is a Word or OO document, this is probably not necessary.  

== Using SVN ==

The base URL for the Volute SVN repository is `https://volute.googlecode.com/svn/trunk`.  In the examples below, we'll assume that we've saved this as an environment variable:
{{{
  % export VOLUTE_PROJECTS https://volute.googlecode.com/svn/trunk/projects
}}}


=== Creating the project ===

Create a directory that will serve as your main directory for your new spec (which we will refer colloquially as _VORobot_); create the rc directory as well.  Then copy in the first version of the document.
{{{
   % mkdir -p VORobot/{rc,samples}
   % mv VORobot.doc VORobot/VORobot-wd.doc
   % ls VORobot
   rc          samples        VORobot-wd.doc
}}}

Initialize this your project with these directories via an `svn import`.
{{{
   % svn import -m 'initial import' VORobot $VOLUTE_PROJECTS/VORobot
}}}

You then need to check this directory out again to have SVN track your changes.  

{{{
   % mv VORobot VORobot-import
   % svn co $VOLUTE_PROJECTS/VORobot VORobot
   ...
   % ls -a VORobot
   .         ..         rc          samples        VORobot-wd.doc
   % rm -r VORobot-import
   % cd VORobot
}}}

=== Updates: Early and Often ===

Never worry about checking in too often:
{{{
   % svn ci -m 'added example to S3.1.2' .
}}}

(Note the dot a the end of the above line, for "everything in this directory.")

=== Releasing a version ===

In SVN, one makes a copy of what ever you want to tag and then not update it again.  It's best to use the `svn copy` command (rather than the shell `cp` followed by a `svn add`); the log will show that the fact that it was copied: it's handy to see exactly what file the tagged version came from.  

First update the dates on the cover page of the spec; then use `svn copy`:
{{{
   % svn copy VORobot-wd.doc rc/WD-VORobot-1.0-20131114.doc
   % svn ci -m 'tagged WD-VORobot-1.0-20131114' .
}}}

(Note the dot at the end of the last line above.)

=== Transitioning to the next phase ===

Use `svn copy` to keep track of provenance:
{{{
   % svn copy VORobot-wd.doc VORobot-pr.doc
}}}

Next edit `VORobot-pr.doc` to update the boiler plate text; then save:
{{{
   % svn ci -m "created PR version" .
}}}

If `VORobot-wd.doc` continues to evolve, be sure to migrate the changes to the PR version, either by hand or with `svn merge`.