Use a Single Version Control System for Everything

Every single artifact related to the creation of your software should be under version control. Developers should use it for source code, of course, but also for tests, database scripts, build and deployment scripts, documentation, libraries and configuration files for your application, your compiler and collection of tools, and so on—so that a new member of your team can start working from scratch.

–Continuous Delivery, Jez Humble, David Farley

I agree, but I’d add to this statement. We don’t keep everything under version control simply to ease the ramp up time for new team members (this is just one of many reasons). An even more important reason to keep everything under version control is because it is imperative that we be able to see all the items related to our project at a given point in time. We need traceability and re-creatability! (I think I just invented a new word.)

In nearly every position I’ve ever been in this question has come up: Should we keep project documentation in the same system as source code? Even in my citation above there seems to be some desire to separate development from documentation (developers do much more than simply write source code). I say to even consider placing project documentation in a separate system is a mistake.

Our project is composed of many items, from code to test to documentation, and all of these items need to reference each other. If our documentation resides in some other system (or in the same system but in a separate repository), it becomes impossible to use a ticketing system to link issues to either documentation or code (or both). Instead, our ticketing system may still be used to write up document needs, but now we have lost the ability to link from a ticket to a changeset that includes non-source code files (think of Redmine or Trac and linking to changesets) .

So what’s the point of keeping documentation in a separate version control or ECM system? I have yet to think of any good reason. I suppose there is a natural tendency to want to separate source code from documentation, but as to why, I have no idea.

I’m not suggesting we should mix documentation throughout source code paths. Naturally, we want to have some reasonable repository/project layout. Here’s what I would do (or something similar):

(Note: In a software medical device environment, there would be DHF and DMR paths in the trunk.) There are many other fine ways to lay out a repository. The point here is simply that it is important to keep everything together in the same version control system. This way we can trace, tag, branch and link issues for a project together.

As you can see in my above example, I’ve used a single repository with all sub-projects below. Others prefer a per-project repository setup. That’s fine, and probably appropriate in many situations, but it doesn’t allow relating issues across projects. I like using a single repository because it becomes much easier to reference related items regardless of project (and, in most issue tracking systems, we will have no problem referencing our project repository using its sub-path).