Source Control Checkins


how the working file should be treated:

  • Revert:  Put the working file back in the state it was in when I checked it out.  Any changes I made while I had the file checked out will be lost.
  • Leave:  Leave the working file alone.  This option will effectively leave the file in a state which we call "Renegade".  It is a bad idea to edit a file without checking it out.  When I do so, Vault notices my transgression and chastises me by letting me know that the file is "Renegade".
  • Delete:  Delete the working file.

I usually prefer to work with "Revert" as my option for how the Undo Check Out command behaves.

Step 3: Checkin

Best Practice: Explain your Checkins Completely

Every SCM tool provides a way to associate a comment when checking changes into the repository. This comment is important. If we consistently use good checkin comments, our repository's history contains not only every change we have ever made, but it also contains an explanation of why those changes happened. These kinds of records can be invaluable later as we forget things.

I believe developers should be encouraged to enter checkin comments which are as long as necessary to explain what is going on. Don't just type "minor change." Tell us what the minor change was. Don't just tell us "fixed bug 1234." Tell us what bug 1234 is and tell us a little bit about the changes that were necessary to fix it. One issue does deserve special mention.  Most SCM tools ask the user to enter a comment when making a checkin.  This comment will be stored in the repository forever along with the changes being submitted.  The comment provides a place for the developer to explain what was changed and why the change was made.

After the file is checked out, the developer proceeds to make her changes.  She edits the file and verifies that her change is correct.  Having completed all this, she is ready to submit her changes to the repository.  Doing so will make her change permanent and official.  Submitting her changes to the repository is the operation we call "checkin."

The process of a checkin isn't terribly complicated:

  1. The new version of the file is sent to the SCM server where it is stored.
  2. The version number of the file in the repository is incremented by one.
  3. The file is no longer considered to be checked out or locked.
  4. The working file on the client side is made read-only again.

The following screendump shows the checkin dialog box from Vault:

Checkins are Additive

It is reassuring to remember one fundamental axiom of source control:  Nothing is ever destroyed.  Let us suppose that we are editing a file which is currently at version 4.  When we checkin our changes, our new version of the file becomes version 5.  Clients will be notified that the latest version is now 5.  Clients that are still holding version 4 in their working folder will be warned that the file is now "Old."

But version 4 is still there.  If we ask the server for the latest version, we will get 5.  But if we specifically ask for version 4, and for any previous version, we can still get it.

Each checkin adds to the history of our repository.  We never subtract anything from that history.

Other Kinds of Checkins
We will informally use the word "checkin" to refer to any change which is made to the repository.  It is common for a developer to say, "I made some checkins this afternoon to

About the author

AgileConnection is a TechWell community.

Through conferences, training, consulting, and online resources, TechWell helps you develop and deliver great software every day.