Preserving version control commit history vs Refactoring and Documentation

Question

It costs almost nothing to use the commit history maintained by the version control system. However, during a major project refactoring (or reorganization / cleanup) effort, functions and classes and even namespaces will be moved around; sometimes several files will be merged together and other files will be split. These changes often lead to the loss of the original commit history of a few files.

In my personal opinion, the up-keeping of the organization of the project is more important than keeping the source code history. Good project organization allows new features to be added continuously with reasonable effort, while the value of source code history appears to be dubious.

Furthermore, with the use of unit testing, regression issues are quickly identified. As long as the latest version continues to satisfy all of the software requirements, do we actually need to preserve the history of the source code?

I understand that any shipped source code must be preserved because of the need to provide support to the customers without requiring them to perform a major version upgrade. But aside from this, is there any value in keeping the history of source code commits?

Does source code commit history play any role in the communications between team members? What if we abolish the commit history, but instead rely on "source code" + "unit testing code" for communication?

Does the existence of commit history make one complacent about the long-term documentation of important information about the project, such as the major design/requirement changes and the streams of thought that drove those changes?

Answer 1

To use commit history for more than "made changes" or "fixed bug" type comments, it should be linked with your issue tracking system. Every change, every commit, should have some issue associated with it so you know what changed, by whom, and why.

As long as the latest version continues to satisfy all of the software requirements, do we actually need to preserve the history of the source code?

Sufficiently complex software rarely has all requirements implemented and all bugs fixed for a multitude of reasons, so I think your assertion here is, let's say, optimistic.

Suppose you are on version 7.8 of your program. But you are supporting, in the field, 12 different active versions, like 1.6, 2.2, 2.8, and so on. Each of these aren't going to be upgraded to the latest version for a variety of reasons, so you are supporting all with bug fixes. A customer finds a bug in your latest 7.8 release. You fix it in 7.8. How do you know how many of the other releases need to be fixed? Without source history and issue tracking you don't.

Answer 2

the value of source code history appears to be dubious.

I've had engineers go back several years into source code looking for answers to why something is the way it is. Sometimes the way things have evolved over time is important to understanding a bug, but it is not something that is typically thought of when documenting things (nor even necessarily documentable).

Also, there may be very good legal reasons for keeping source code history. Most source code dumpster-diving that I've had to do (as a build/SCM engineer) has been at the request of my company's legal department.

Answer 3

As long as the latest version continues to satisfy all of the software requirements, do we actually need to preserve the history of the source code?

But aside from this, is there any value in keeping the history of source code commits?

Yes to both. It can be useful to know when something was changed, by whom and why. If you lose your history, your ability to do this is impacted.

Does source code commit history play any role in the communications between team members? What if we abolish the commit history, but instead rely on "source code" + "unit testing code" for communication?

Yes it does. The "source code" + "unit testing code" only approach doesn't tell you who / when / why.

Does the existence of commit history make one complacent about the long-term documentation of important information about the project, such as the major design/requirement changes and the streams of thought that drove those changes?

I suppose you could say that it does. But few developers ever thoroughly document the changes in requirements / design. And certainly almost nobody records the stream of thought that drove the initial development, or the subsequent modifications. Having the commit history (and especially the commit log messages), and crosslinks to the issue / bug tracking system at least provide you something to go from. And that's better than nothing, or a set of release snapshots.