/[volute]/wiki/RaysIVOADocDevInVolute.wiki
ViewVC logotype

Contents of /wiki/RaysIVOADocDevInVolute.wiki

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2350 - (show annotations)
Thu Nov 14 23:45:16 2013 UTC (7 years, 2 months ago) by rplante@ncsa.uiuc.edu
File size: 5771 byte(s)
Edited wiki page RaysIVOADocDevInVolute through web user interface.
1 #summary Tracking IVOA Document Development in Volute
2
3 = Tracking IVOA Document Development in Volute: Ray's Approach =
4
5 == Introduction ==
6
7 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.
8
9 === Example Document Projects ===
10
11 The following projects best exemplify the process I use:
12
13 * [https://code.google.com/p/volute/source/browse/#svn%2Ftrunk%2Fprojects%2Fregistry%2FSimpleDALRegExt registry/SimpleDALRegExt]
14 * [https://code.google.com/p/volute/source/browse/#svn%2Ftrunk%2Fprojects%2Fregistry%2FStandardsRegExt registry/StandardRegExt]
15 * [https://code.google.com/p/volute/source/browse/#svn%2Ftrunk%2Fprojects%2Fregistry%2FVODataService registry/VODataService]
16
17 Part of these standards were various XML Schema (.xsd) files; these were versioned as well.
18
19
20 == SVN Organization ==
21
22 The two most important part of the organization are:
23 * 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
24 * 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.
25
26 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.
27
28 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.
29
30 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.
31
32 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.
33
34 == Using SVN ==
35
36 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:
37 {{{
38 % export VOLUTE_PROJECTS https://volute.googlecode.com/svn/trunk/projects
39 }}}
40
41
42 === Creating the project ===
43
44 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.
45 {{{
46 % mkdir -p VORobot/{rc,samples}
47 % mv VORobot.doc VORobot/VORobot-wd.doc
48 % ls VORobot
49 rc samples VORobot-wd.doc
50 }}}
51
52 Initialize this your project with these directories via an `svn import`.
53 {{{
54 % svn import -m 'initial import' VORobot $VOLUTE_PROJECTS/VORobot
55 }}}
56
57 You then need to check this directory out again to have SVN track your changes.
58
59 {{{
60 % mv VORobot VORobot-import
61 % svn co $VOLUTE_PROJECTS/VORobot VORobot
62 ...
63 % ls -a VORobot
64 . .. rc samples VORobot-wd.doc
65 % rm -r VORobot-import
66 % cd VORobot
67 }}}
68
69 === Updates: Early and Often ===
70
71 Never worry about checking in too often:
72 {{{
73 % svn ci -m 'added example to S3.1.2' .
74 }}}
75
76 (Note the dot a the end of the above line, for "everything in this directory.")
77
78 === Releasing a version ===
79
80 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.
81
82 First update the dates on the cover page of the spec; then use `svn copy`:
83 {{{
84 % svn copy VORobot-wd.doc rc/WD-VORobot-1.0-20131114.doc
85 % svn ci -m 'tagged WD-VORobot-1.0-20131114' .
86 }}}
87
88 (Note the dot at the end of the last line above.)
89
90 === Transitioning to the next phase ===
91
92 Use `svn copy` to keep track of provenance:
93 {{{
94 % svn copy VORobot-wd.doc VORobot-pr.doc
95 }}}
96
97 Next edit `VORobot-pr.doc` to update the boiler plate text; then save:
98 {{{
99 % svn ci -m "created PR version" .
100 }}}
101
102 If `VORobot-wd.doc` continues to evolve, be sure to migrate the changes to the PR version, either by hand or with `svn merge`.

msdemlei@ari.uni-heidelberg.de
ViewVC Help
Powered by ViewVC 1.1.26