TweetFollow Us on Twitter

Revisionist History
Volume Number:12
Issue Number:6
Column Tag:Version Control

Revisionist History

Organic tools for an unpleasant task

By Paul Snively

Rationale

Revision control is often neglected. Of all the companies I’ve been with, only three have even attempted to use it - and at two of these, the decision was driven by engineers on particular projects, sometimes with the result that projects couldn’t share files because their revision control systems weren’t compatible. Don’t get the idea that I’m a great lover of revision control, either. I’ve always found RCS, Projector, and previous versions of SourceSafe to be so confusing and unwieldy as to be more trouble than they were worth for groups of anything less than about five users. If I hadn’t found a couple of systems worth writing about, this article wouldn’t exist.

Nevertheless, two observations about software development today will demonstrate the pertinence of the subject. First, many of us are doing cross-platform development and struggling to maintain feature-for-feature compatibility between platforms. Second, a lot of what we professional programmers do these days isn’t so much original development as synthesis - taking a collection of code, some of which we wrote and some of which we didn’t, and gluing it all together, making whatever changes to the pieces prove necessary along the way. A revision control system becomes indispensable in cases where you have to track common code vs. platform-specific code and in cases where you’re using some existing code and making changes to it (possibly at the same time that the original author makes changes to it!). And of course, you could be trying to do both at the same time.

Note that neither of these common scenarios has anything to do with having multiple programmers on a project. These are situations that I, and probably you, have encountered even when we’re working on things all by our lonesome. Don’t be seduced into believing that revision control is only for projects involving large groups.

Many of you may have prior experience with one of the older revision control systems - Projector/SourceServer for those of you who cut your teeth on the MPW or Symantec environments, SCCS or RCS for us greybeards in the industry. I’d like to take a look at a couple of relative newcomers to most of us, even though they’ve both been around for a while: Metrowerks’ CodeManager, née SourceSafe, and UNI Software Plus’ VOODOO.

Is It Safe?

CodeManager 1.0.3 (DR1, with patches available at http://www.metrowerks.com/ tools/software/updates/cm1) is the Macintosh version of SourceSafe, which was purchased some time ago by Microsoft. As a result, one of CodeManager’s major selling points is its cross-platform availability. Unfortunately, one aspect of CodeManager that eases the burden of keeping it cross-platform is that it is a command-line system - that is, it runs as a set of tools under MPW or ToolServer. This is probably not so bad if you’re an old hand at SCCS/RCS/Projector, especially if you’re still an MPW user anyway. As a CodeWarrior user since DR/1, though, I can afford neither the disk nor the RAM space to maintain both CodeWarrior CW8 and MPW at the same time, so I had to get ToolServer up and running under CodeWarrior. That alone was a sufficiently daunting task that it nearly made me give up on CodeManager, which would have been a shame, because there are things to like about CodeManager. Hint to you: if you’re going to install CodeManager under ToolServer, don’t forget to rename UserStartup•CodeManager to UserStartupTS•CodeManager. Hint to Metrowerks: most of your CodeManager users are also likely to be CodeWarrior users, so how about providing an installer that will install ToolServer and CodeManager into an existing CodeWarrior installation and then delete the desktop file(s) before restarting, thereby forcing the Finder to rebuild the desktop?

Once I got CodeManager up and running under ToolServer, I was pleasantly surprised to find that it doesn’t remind me as much of SCCS/RCS/Projector as I had expected it to.

Projects vs. Files

Historically, revision control systems that I’ve used have been file-centric: useful for tracking changes to any given file in a project, but poor at tracking changes to the project (integrating one file’s contents into another, renaming a file in the project, renaming a folder, moving a file from one folder to another, etc.). If you’ve spent any time wrangling any but the smallest project, you probably know that getting the structure of the project right is at least as difficult as getting the content of the project right.

CodeManager, to its considerable credit, is project-based. Not only does it support traditional file-level revision control, but groups of files belong to projects and can be referred to collectively. Projects can be nested, and in this sense projects resemble folders. Unlike folders, however, projects can be deleted and later recovered.

Projects can also share files - an update to a file in one project is automagically reflected in the file in any other projects that include it. This feature is especially handy when you have multiple projects that rely on a common code base. As long as the common code is shared among all the projects that use it, all the projects are kept up to date without any extra effort.

It may be the case, though, that your project is using code from someone else’s project and your schedule is somewhat ahead of theirs. You may need to freeze your project before they do. That’s ok - you can “pin” whatever file(s) they’re sharing with you at any version at any time. This doesn’t break the shared link; it just gives you a specific “snapshot” of the revisions of that file. You can unpin the file at any time to catch up to the other revisions.

In a similar vein, you can “branch” a shared file if you need to revise it in directions that you know differ from those of the other sharers of the file. Unlike pinning, branching does break the shared link. However, a history of the link is still maintained, so you can examine the common heritage of the branches if you need to.

As you might expect, CodeManager also allows you to merge branches of a file, in the event that the combined revisions would be appropriate for all projects sharing the branches. It’s perhaps worth pointing out that CodeManager can handle both text files and binary files, although its means for determining which is which is questionable: it reads the file and, if and only if it discovers any zero bytes, considers it a binary file. This behavior can be overriden with an environment variable that specifies, say, that all files whose names end with .sit, .µ, or .rsrc are binary files, and all others should be considered text. There are also command-line options to the relevant commands to specify that when comparing files both forks are to be compared. CodeManager’s ability to do diffs and merges on binary files is one of the things that set it apart from earlier revision control systems.

My favorite project-based feature, though, is labels. You can attach a label to an entire project at any point in the revision of that project, and then, at any point down the road, you can retrieve the entire project by label. The most obvious application of labels to me is at major milestones: when your project goes alpha, give it a label saying so; when it goes alpha two, label it; when it goes beta, label it. This way you have an air-tight history of your project’s milestones, which can be extremely helpful in analyzing the project’s schedule, budget, size, feature set, bug history, etc. In particular, imagine how much your QA staff doing regression testing will love being able to retrieve any version of the project any time they need to.

Finally, a feature that is, as far as I know, completely unique to CodeManager: you can configure it in such a way that multiple people can check out a file at the same time, and when the various users of the file check their revisions back in, CodeManager will attempt to merge them. If none of the users have modified the same line, then the merge is considered to be without conflicts and happens silently. If, on the other hand, two or more users have modified the same line, then whoever checks their revisions in later will have the opportunity to resolve the conflict, hopefully in consultation with whoever checked in the earlier revision. Many’s the time I’ve wished for a revision control system that recognized that it’s quite rare for my coworkers and myself to be working on the same lines in a source file, but it’s relatively common for us to need to work on the same file. CodeManager makes this as painless as I think it can realistically be made.

Administration of CodeManager is a straightforward matter of editing some text files and possibly using some extra tools once you have logged in under the Admin account. I encountered no particular surprises here, good or bad.

Déjà Voodoo

VOODOO 1.7, from UNI Software Plus in Austria, takes a similar tack to CodeManager in that it is project- rather than file-based, and also stores deltas of either text or binary files for space-efficiency. VOODOO, however, takes the project-based concept a step further by supporting the notions of a component, a variant, and a revision, all of which are orthogonal to each other - VOODOO stands for “Versions Of Outdated Documents Organized Orthogonally,” which beats “BASIC” for the Most Tortuous Acronym award. “Orthogonal” just means that each of these concepts is treated independently of the others: in other words, VOODOO cleanly differentiates among the components of a project, the variants of those components, and the revisions of those variants.

For example, let’s say that, being serious about what you do, you do all of your development on your PowerMac with no optimizations on - especially instruction scheduling, because that totally wrecks the mapping from your source code to your object code, and Metrowerks’ debugger gets confused (no slam to Metrowerks; practically any source-level debugger gets confused in the presence of instruction scheduling). Of course you generate a .SYM file, and maybe you even include traceback tables because MacsBug now groks them. Of course, your code is big and slow, but that’s because it’s your development version. On the other hand, by the time you’re ready to ship, it’s out with the traceback tables, out with the .SYM file, and hopefully in with the instruction scheduling, global optimizations, etc.

That’s one component - the project file - with two variants, debugging and optimized, and some number of revisions of those variants, such as when you try the level-four global optimizations and they cause your project to crash, so you scale down to level-two global optimizations and everything works fine.

This may sound like a lot to keep track of, and it is, which leads me to another favorite feature of VOODOO, namely its graphical interface. As an example, consider McKinley. This is my shot at creating a Netscape 2.0 plug-in that supports VRML 2.0 and the “Moving Worlds” proposal from Netscape, Silicon Graphics, and Apple, with object behaviors being programmable in Scheme. In the McKinley project, there are four distinct major subsystems, namely Apple’s freely available 3DMF parser, the freely available Mesa 3D graphics library, the freely-available MzScheme Scheme interpreter, and the freely available Netscape plug-in shell. With all of these sources yanked off the net, it’s a great project for revision control. VOODOO’s graphical representation looks like Figure 1.

The plain rectangular boxes are structure nodes. Like folders on your disk, they’re there to help you keep organized.

The rectangles with the document icons are components. A component typically maps onto a file, and in fact VOODOO simplifies that mapping by allowing you to add files to your project as components. VOODOO will also allow you to drag and drop files into your structure nodes as you’re defining the structure of your project. Symantec users, rejoice! You can drag files directly from your project files into VOODOO. CodeWarrior users, grumble! You can drag and drop files into your projects, but not out. Interestingly enough, VOODOO is also a drag-in-only proposition. (An analogy with Roach Motel suggests itself.)

Figure 1. How a VOODOO project looks

The circles are used to indicate the variants of a component. In the McKinley project, you can see that of the visible parts only the project files themselves have more than one variant, debugging and optimized, as described above. Source files might too, however - for example, if you wished to maintain a variant of your source with debugging-assistance code included vs. one without. In the shot above, each variant actually refers to the same file. When you actually branch off a new variant of a file, it looks like this:

Figure 2. Two variants referring to one object
vs. an object for each variant

The free-standing document icons are called version groups. In the 68K case, there’s only one, because the 68K optimizer doesn’t break the debugger so badly. In the PPC case, there are two, to indicate that the debugging and optimized variants refer to two different objects. This takes a little getting used to, but it’s very convenient to be able to easily specify whether you want a development variant or a production variant of your project. Variants might also be used for those components of your project that just can’t be completely identical across platforms (you might have a Macintosh variant and a Win32 variant, for example).

Finally, you’ll notice that some of the structure nodes have arrows extending from them. This indicates that they have child nodes, but that those nodes are currently collapsed so as to allow you to focus on the portion of the project at hand.

Once you’ve defined the structure of your project, actually using VOODOO to store and fetch components is simple. After making changes to files, you can just drag them to the VOODOO project window to store them and VOODOO will automatically figure out where in the tree they go. Failing that, you can use a dialog to select which components to store, specify locking of local copies, and the like.

Fetching components is practically as easy: you can select any structure node, a component node if it doesn’t have more than one version group, or any version group icon, and fetch the most recent version(s) of those components, specifying in the process whether you want the relevant version group(s) locked, etc.

Being project-based, VOODOO also tracks the history of the project as a whole: you can view structure changes, data changes, or both. As with CodeManager, you can name particular points in time (called “Defining a Configuration” in VOODOO), and when viewing the history of the project, you can roll back instantly to any such named point in time.

Conclusions

Revision control has come a long way since my SCCS/RCS/Projector days. It’s good to see two systems that take a holistic stance toward projects, recognizing that a project that I call “1.0b1” consists of some components that have been revised 100 times and others that haven’t been at all. And it’s nice that they both deal with binary files as well as text.

CodeManager does some things that I’d love to see in VOODOO. The feature of allowing multiple checkouts of text files and making an effort to merge them together upon check-in is a big win for me. Generally speaking, VOODOO’s uniform treatment of everything as a binary is elegant, but some kind of comparison/merging facility would be a big help. And if you work in a mixed shop, SourceSafe/CodeManager is very hard to beat.

On the other hand, VOODOO does some things that I’d love to see in CodeManager. Being a standalone application with a graphical interface and drag and drop support is one. Also, there’s its uniform treatment of variants as well as revisions (although careful use of branching in CodeManager could probably accomplish the same result).

Personally, I use VOODOO on an everyday basis. It’s the tool that got me religious about revision control in the first place. It makes revision control make sense to me, and makes it a fun process rather than a chore. Some time ago, in responding in netnews to a query about revision control, I said about VOODOO:

“I use VOODOO 1.6 practically every day, and I continue to be amazed that it took this long for revision control to become even reasonable, let alone pleasant. VOODOO recognizes that not all the world is a text file. It recognizes that variants are distinct from revisions. It recognizes that I’m using a windowing system with a mouse. At this point, no matter where I go, no matter what other development tools I’m using, I’ll be using VOODOO to keep me from shooting myself in the foot when it comes to version control.”

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Adobe InCopy CC 2018 13.0.0.123 - Create...
InCopy CC 2018 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous InCopy customer). Adobe InCopy CC 2018, ideal for large team projects... Read more
OnyX 3.3.8 - Maintenance and optimizatio...
OnyX is a multifunction utility that you can use to verify the startup disk and the structure of its system files, to run miscellaneous maintenance and cleaning tasks, to configure parameters in the... Read more
Merlin Project 4.3.1 - $289.00
Merlin Project is the leading professional project management software for OS X. If you plan complex projects on your Mac, you won’t get far with a simple list of tasks. Good planning raises... Read more
DiskCatalogMaker 7.2.5 - Catalog your di...
DiskCatalogMaker is a simple disk management tool which catalogs disks. Simple, light-weight, and fast Finder-like intuitive look and feel Super-fast search algorithm Can compress catalog data for... Read more
WhatsApp 0.2.6426 - Desktop client for W...
WhatsApp is the desktop client for WhatsApp Messenger, a cross-platform mobile messaging app which allows you to exchange messages without having to pay for SMS. WhatsApp Messenger is available for... Read more
Ableton Live 9.7.5 - Record music using...
Ableton Live lets you create and record music on your Mac. Use digital instruments, pre-recorded sounds, and sampled loops to arrange, produce, and perform your music like never before. Ableton Live... Read more
Maintenance 2.3.5 - System maintenance u...
Maintenance is a system maintenance and cleaning utility. It allows you to run miscellaneous tasks of system maintenance: Check the status of the hard disk Repair permissions Run periodic scripts... Read more
OnyX 3.3.8 - Maintenance and optimizatio...
OnyX is a multifunction utility that you can use to verify the startup disk and the structure of its system files, to run miscellaneous maintenance and cleaning tasks, to configure parameters in the... Read more
Merlin Project 4.3.1 - $289.00
Merlin Project is the leading professional project management software for OS X. If you plan complex projects on your Mac, you won’t get far with a simple list of tasks. Good planning raises... Read more
WhatsApp 0.2.6426 - Desktop client for W...
WhatsApp is the desktop client for WhatsApp Messenger, a cross-platform mobile messaging app which allows you to exchange messages without having to pay for SMS. WhatsApp Messenger is available for... Read more

Guns Royale guide - beginner tips and tr...
If you've been itching to find a mobile battle royale game like Player Unknown's Battlegrounds, you're finally in luck. Guns Royale is a new survival shooter that takes all of the things you love about good ol' PUBG and puts it in a tidy mobile... | Read more »
What we know about Animal Crossing on mo...
At last, we'll be receiving some news about the mobile version of Animal Crossing in a special Nintendo Director at11 PM on October 24. There's been little word on the game since it was first announced, having been met with a series of delays.... | Read more »
Darts of Fury guide - how to rise in the...
Darts of Fury is a new, immensely absorbing darts game from indie studio Yakuto. It's darts in its purest form, but collectible darts and other upgrades give this game an addictive edge that's hard to shake. As your progress out of the beginner... | Read more »
ICEY (Games)
ICEY 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: ICEY is a 2D side-scrolling action game. As you follow the narrator's omnipresent voice, you will see through ICEY's eyes and learn the... | Read more »
The best new games we played this week -...
We've made it, folks. Another weekend is upon us. It's time to sit back and relax with the best new releases of the week. Puzzles, strategy RPGs, and arcade games abound this week. There's a lot of quality stuff to unpack this week, so let's hop... | Read more »
Wheels of Aurelia (Games)
Wheels of Aurelia 1.0.1 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.1 (iTunes) Description: | Read more »
Halcyon 6: Starbase Commander guide - ti...
Halcyon 6 is a well-loved indie RPG with stellar tactical combat and some pretty good writing, too. It's now landed on the App Store, so mobile fans, if you're itching for a good intergalactic adventure, here's your game. Being a strategy RPG, the... | Read more »
Game of Thrones: Conquest guide - how to...
Fans of base building games might be excited to know that yet another entry in the genre has materialized - Game of Thrones: Conquest. Yes, you can now join the many kingdoms of the famed book series, or create your own, as you try to conquer... | Read more »
Halcyon 6: Starbase Commander (Games)
Halcyon 6: Starbase Commander 1.4.2.0 Device: iOS Universal Category: Games Price: $6.99, Version: 1.4.2.0 (iTunes) Description: An epic space strategy RPG with base building, deep tactical combat, crew management, alien diplomacy,... | Read more »
Legacy of Discord celebrates its 1 year...
It’s been a thrilling first year for fans of Legacy of Discord, the stunning PvP dungeon-crawling ARPG from YOOZOO Games, and now it’s time to celebrate the game’s first anniversary. The developers are amping up the festivities with some exciting... | Read more »

Price Scanner via MacPrices.net

27″ 3.4GHz iMac on sale for $1699, save $100
Amazon has the 27″ 3.4GHz iMac (MNE92LL/A) on sale today for $1699 including free shipping. Their price is $100 off MSRP, and it’s the lowest price available for this model (except for Apple’s $1529... Read more
Clearance 2016 15″ MacBook Pros available for...
B&H Photo has leftover 2016 15″ MacBook Pros available for up to $700 off original MSRP. Shipping is free, and B&H charges NY & NJ sales tax only: – 15″ 2.7GHz Touch Bar MacBook Pro Space... Read more
Save $100 on 13″ MacBook Airs, prices start a...
Adorama has 2017 13″ MacBook Airs on sale today for $100 off MSRP including free shipping. Adorama charges NY & NJ sales tax only: – 13″ 1.8GHz/128GB MacBook Air (MQD32LL/A): $899, $100 off MSRP... Read more
1.4GHz Mac mini available for $399, $100 off...
TigerDirect has the 1.4GHz Mac mini on sale today for $399 including free shipping. Their price is $100 off MSRP, and it’s the lowest price available for this model. Although currently out of stock,... Read more
21″ 2.3GHz iMac on sale for $999, save $100
MacMall has the 21″ 2.3GHz iMac (MMQA2LL/A) on sale today for $999 including free shipping. Their price is $100 off MSRP, and it’s the lowest price available for this model. Read more
12″ iPad Pros on sale for $50 off MSRP, no ta...
Adorama has 12″ iPad Pros on sale today for $50 off MSRP. Shipping is free, and Adorama charges sales tax in NY & NJ only: – 12″ 64GB iPad Pro: $749, save $50 – 12″ 256GB iPad Pro: $899, save $50... Read more
9″ iPads on sale for $30 off, starting at $29...
MacMall has 9″ iPads on sale for $30 off including free shipping: – 9″ 32GB iPad: $299 – 9″ 128GB iPad: $399 Read more
Apple restocks full line of refurbished 13″ M...
Apple has restocked a full line of Apple Certified Refurbished 2017 13″ MacBook Pros for $200-$300 off MSRP. A standard Apple one-year warranty is included with each MacBook, and shipping is free.... Read more
13″ 3.1GHz/256GB MacBook Pro on sale for $167...
Amazon has the 2017 13″ 3.1GHz/256GB Space Gray MacBook Pro on sale today for $121 off MSRP including free shipping: – 13″ 3.1GHz/256GB Space Gray MacBook Pro (MPXV2LL/A): $1678 $121 off MSRP Keep an... Read more
13″ MacBook Pros on sale for up to $120 off M...
B&H Photo has 2017 13″ MacBook Pros in stock today and on sale for up to $120 off MSRP, each including free shipping plus NY & NJ sales tax only: – 13-inch 2.3GHz/128GB Space Gray MacBook... Read more

Jobs Board

*Apple* Professional Learning Specialist - A...
Job Summary The Apple Professional Learning Specialist is a full-time position for one year with Apple in the Kanawha, WV area. This position requires a high Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Project Engineer, *Apple* Education Profess...
Project Engineer, Apple Education Professional Services Job Number: 113143353New York City, New York, United StatesPosted: Oct. 17, 2017Weekly Hours: 40.00 Job Read more
Commerce Software Engineer, *Apple* Media P...
Commerce Software Engineer, Apple Media Products Job Number: 113092072New York City, New York, United StatesPosted: Oct. 19, 2017Weekly Hours: 40.00 Job Summary With Read more
Engineering Manager, *Apple* Retail Enginee...
# Engineering Manager, Apple Retail Engineering Job Number: 58139948 Santa Clara Valley, California, United States Posted: 20-Oct-2017 Weekly Hours: 40.00 **Job Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.