SVN Usage with Silva
By Andy Altepeter
If you are making modifications to core Silva components (e.g. files in /Products/Silva, /Products/SilvaDocument, etc) the best way to maintain these changes across Silva upgrades is to use svn. Here’s the procedure:
Download a fresh copy of each Silva product (the version you're currently using!), and import them into svn. Before you import, you need to construct a folder layout like:
vendor/
/Silva/
/current
Inside Silva/current is the Silva 1.4.3 product. After you do an ‘svn import’ of this layout, you create a tag, like:
svn copy vendor/Silva/current vendor/Silva/1.4.3 -m "Silva 1.4.3 vendor tag"
Now that you have the official Silva release in svn, copy it to another area of svn. This area will contain the Silva release that you will modify:
svn copy vendor/Silva/current UCL/Silva/trunk
Now checkout this copy:
svn co UCL/Silva/trunk Silva
You now have a working copy of your UCL Silva version. Locate all of the changes you’ve made to Silva 1.4.3, and make those same changes here. To locate those quickly you can use:
diff -ur Silva-1.4.3 MySilva1.4.3
(Here, Silva-1.4.3 is the official Silva release, and MySilva1.4.3 is your modified copy.)
Once you’ve made all your changes (and tested them, of course!), commit those changes:
svn commit -m "UCL Silva 1.4.3"
(Of course, you can be doing commits in smaller intervals.)
Then, create a tag of your Silva 1.4.3, so you can reference it later:
svn copy UCL/Silva/trunk UCL/Silva/tags/1.4.3
Now you’re in a good spot to quickly perform upgrades to the core Silva products, and maintain your changes. In the svn world, these are called vendor drops / vendor branches. What we’ve done so far is create a vendor drop, and a branch off that vendor drop where you’re custom changes to the vendor code will take place.
Basically the procedure goes like:
- Checkout your vendor drop of Silva 1.4.3. Upgrade it to Silva 1.5.9. This involves removing obsolete files, and installing 1.5.9 on top of 1.4.3.
- Checkin your changes, and tag the ‘current’ folder as '1.5.9' (e.g. svn copy vendor/Silva/current vendor/Silva/1.5.9)
- Checkout your UCL version of 1.4.3 (from UCL/Silva/trunk)
- Do a 3-way merge between the vendor drop of Silva 1.4.3, the vendor drop of Silva 1.5.9, and your working copy of UCL Silva 1.4.3). This step will automatically upgrade your custom branch of Silva. Some places where you've updated code, but not all, svn will be unable to merge for you. But don't worry! It clearly informs you where these conflicts are so you can more easily bring your merge into a consistent state.
- Once your Silva 1.5.9 branch is functional, commit it, and tag it, e.g.:
svn commit svn copy UCL/Silva/trunk UCL/Silva/tags/1.5.9
I've written a knowledgebase article the goes over this in more detail: http://knowledgebase.its.bethel.edu/articles/333/
The svn book also has a very good description of how to manage these so-called 'vendor drops'. I link to the book in my article.
