Checkins

[article]

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

TechWell Contributor's picture TechWell Contributor

The opinions and positions expressed within these guest posts are those of the author alone and do not represent those of the TechWell Community Sites. Guest authors represent that they have the right to distribute this content and that such content is not violating the legal rights of others. If you would like to contribute content to a TechWell Community Site, email editors@techwell.com.

AgileConnection is one of the growing communities of the TechWell network.

Featuring fresh, insightful stories, TechWell.com is the place to go for what is happening in software development and delivery.  Join the conversation now!

Upcoming Events

Nov 09
Nov 09
Apr 13
May 03