Time Series Cube DM - IVOA Note

[Markus Demleitner]

Hi Tom,

On Wed, Apr 05, 2017 at 01:25:15PM +0000, Tom Donaldson wrote:
> Hi Markus,
> On Apr 5, 2017, at 8:28 AM, Markus Demleitner <msdemlei at ari.uni-heidelberg.de<mailto:msdemlei at ari.uni-heidelberg.de>> wrote:
>> (1) volute is a VCS, so it does versioning by itself.  It would
>> therefore be great if you just kept the latest version of each
>> document in there and *not* use version number in file names.  If
>> people actually want to go back in time, they can use the standard
>> svn mechanisms (svn log, svn co -r...; yes, with office files there
>> are no diffs, which is regrettable, but the full files are still
>> there).  That would already clean up a directory like
>> http://volute.g-vo.org/svn/trunk/projects/dm/vo-dml/doc/ very nicely.
> 
> When we???re creating ???official??? documents, the process
> requires the files tracked on ivoa.net<http://ivoa.net> to include
> version numbers in the names, and I think it makes sense to have
> the working copies in volute match those official file names.  We

I'm not quite sure where this helps: 

* As the file name for all but REC contain dates, they have to be
  renamed before submitting anyway, so there's little convenience to be
  gained by reflecting future (?) names in the VCS, is there?  


* The history of the released files is kept at the IVOA document
  repository -- so there's little point for volute to reproduce that
  archive, is there?  I'd even say there's a risk that the IVOA
  document repo and volute will diagree on the content of a given
  released version ("PR-1.0-20170406"), and that's never a good
  thing.

* To link released files in the document repo with volute revisions
  (which makes a lot of sense in the case of fine-grained
  commits[1]), I'd much rather see SVN tags or (perhaps even better)
  revision notices in the documents themselves.

Or am I arguing against something you didn't say?

> I generally I agree that "baked" files don't belong in VCS,
> but I think it???s a legitimate exception when we want the
> "baked" files to be easily URL accessible.  Some of these
> PDFs may fall into that category.

There's always a tradeoff between author convenience and technical
considerations, so this is not a matter of "take these out ASAP".

However, since PDF generation generally introduces machine-specific
signatures embedded in binary-looking stuff, a generated PDF in VCS
will almost certainly produce edit conflicts even when changes are
otherwise mergeable. In that sense, generated PDFs in the VCS do
cause operational issues.

I guess what I'm trying to say is: If you can, put the PDF on the
ivoa wiki or on external web pages.  It's helping smooth cooperation
on the documents.

Thanks,

           Markus

[1] The VCS operator in me cringes on the thought of "fine grained
commits" of big binary blobs like office files, but disk space is
cheap, and with good commit messages that's still helpful.