As I updated our local JsonCpp source tree from v0.5.0 to v0.6.0-rc2 (slightly hacked-up as JsonCpp doesn't support our CodeSourcery GCC for ARM toolchain out of the box), I got a rude surprise — developers that have long since moved on from our team left the svn:external to this source tree pointing to trunk HEAD.

What does this mean?

It means that every single revision of our multiple projects that use this dependency, ever, have retroactively obtained this JsonCpp update. This is a really bad thing.

  1. For one, I'm only updating to JsonCpp v0.6.0-rc2 to get 64-bit integer support that we need in one particular branch of a project, but since it's not an official production release I'm not ready to do the same thing in our other production-level projects and risk losing GA quality.

  2. And if there were any changes that needed to be made in our code to support the new JsonCpp version, those older revisions would of course not have them and thus every historical revision in our SVN repository would be permanently and unrecoverably broken. I would have to roll-back my JsonCpp source tree and start again in a new module for the new version, which is wasteful and introduces a maintenance overhead.

Ideally, the svn:external would, from the start, have pointed to a specific revision in the JsonCpp source tree, so that no matter how far in the future you checked out a historical copy of our code, you would always get the correct JsonCpp version as it was known at the time that the code was written and committed. Better, tagging specific points in the JsonCpp history makes this a cinch.

From the SVN red book:

Use explicit revision numbers

You should strongly consider using explicit revision numbers in all of your externals definitions, as described above. Doing so means that you get to decide when to pull down a different snapshot of external information, and exactly which snapshot to pull. Besides the common sense aspect of not being surprised by changes to third-party repositories that you might not have any control over, using explicit revision numbers also means that as you backdate your working copy to a previous revision, your externals definitions will also revert to the way they looked in that previous revision, which in turn means that the external working copies will be updated to match they way they looked back when your repository was at that previous revision. For software projects, this could be the difference between a successful and a failed build of an older snapshot of your complex code base.

The moral of the story?
Never point svn:externals to HEAD! EVER! **


** Well, in a temporary feature/bug-specific branch might be okay, since you'll soon be closing that and never looking back. But don't tell anyone…