CSC/ECE 517 Fall 2009/wiki1a 4 co

Best Practices For Source-Control Management With Version-Control Systems

  “Tip 23: Always Use Source Code Control” 
         – Hunt and Thomas, The Pragmatic Programmer [HT 00]

In software development, change is almost always inevitable [P 05] . Using a source configuration management (SCM) system (also known as a Source Code Control System (SCCS) or version-control system) can help individuals and teams manage the changes that occur during the software development process [D 90]. This article will provide the reader with basic information, and direct the reader to additional reading for more in-depth consideration.

Why Source Code Control is Necessary

According to Pressman, “Change is inevitable when computer software is built. [P 05]” He suggests four primary reasons for change:

• New business or market conditions
• New customer needs
• Reorganization, business growth, or downsizing
• Budgetary or scheduling constraints

Each of these reasons can cause changes in project requirements, in project priorities, or in the resources available to create or enhance a project. An SCM can enable a project team to handle changes in requirements and priorities.

Example

Company XYZ has asked the developers of Software Q for a version which tracks product price changes. This change (the Product Price Change feature) will take approximately 4 months to complete. During the second month, Company XYZ has changed it's mind and instead wants to make a change how product pricing is approved (the Product Price Approval feature).

• If the makers of Software Q do not have their product under an SCM, they may find it difficult to reproduce the original software after two months of development. Additionally, they may have made software fixes unrelated to the Product Price Change feature that they would want to keep in the original software, but without an SCM those changes may be indistinguishable from feature changes.
• If the makers of Software Q do have their project under an SCM, they could create two branches for their software development: One for bug fixes and one for the new feature. They could easily go back to the original version and create a new development branch for the Product Pricing Approval feature and still maintain their bug fix branch. In addition, they can archive the Product Pricing Change feature branch and keep it around in case Company XYZ changes it's mind and decides it wants the feature.

Managing changes with an SCM enables engineers to focus on technical work, and enables project managers to control changes which can affect project outcomes. Further, an SCM can maintain a history of the work done on a project so it is easier to understand why changes are made, even well after the original change is made.

Understanding Basic Concepts

For the reader new to SCM, there are a few basic terms and concepts that should be understood before best practices are considered:

• Check-in or Commit – Writing changes to the source code repository
• Lock-Modify-Unlock Model: An SCM model that requires a developer to reserve or lock a source file before making changes to the file. This lock prevents other developers from modifying the file.
• Change-Modify-Merge Model: An SCM model that allows multiple developers to make changes to a source file. Upon commit, if the source file has been updated by another developer, a merge of the updated file with the developers change is necessary in order to preserve all the updates. Depending on the SCM and the nature of the change, the merge operation may be performed by the SCM or by the developer.
• Revision – The version identifier of the source file (e.g. v1, v2, v2.1, etc). Each commit of a source file will produce a new revision value.
• Baseline – The root of a development stream, where changes that are intended to be integrated into the main project will eventually migrate.
• Branch – An offshoot from the baseline where prototype, testing, or other work can be performed that does not immediately affect the baseline. Eventually, a branch may be merged back into the baseline.

Understanding the Two Models

As mentioned above, SCMs can provide one of two models, the Lock-Modify-Unlock Model or the Change-Modify-Merge Model. The following diagrams can help the reader understand a little bit more about the differences between these two models.

---

This figure demonstrates a Lock-Modify-Unlock SCM model. You can see that when Carmen does a check-out on File1.java, the file is not available to Ramdas for editing. In the picture, Carmen is shown to have direct access to the file in the SCM, but it is more likely that a copy of the file is provided to Carmen. In any case, the end-result is that Carmen has exclusive control over changes to File1.java until he does a check-in or commit.

---

This figure and the next two figures demonstrate a Change-Modify-Merge SCM model. You can see that both Carmen and Ramdas are able to check-out File1.java and make changes to their private copy. Neither one of them is prevented from making changes to the file.

---

Carmen is the first one to commit or check-in his changes. His changes overwrite the original version with a v2 version.

---

Now Ramdas attempts to check-in his changes. Because File1.java is a different version than what Ramdas originally checked-out, and additional operation is required before a check-in can be completed: A merge operation. Depending on the type of changes that have been done, and the type of SCM, the merges may be incorporated automatically by the SCM, or the SCM may request guidance from Ramdas before the change is committed. In any case, with this model, both Carmen and Ramdas were able to continue their development work despite both needing to work with the same source code file.

---

Advice on Using an SCM or SCCS

There is differing advice on using an SCM to manage projects, but there are some consistent messages:

• Use a source configuration management product: When working on teams, there is a general consensus that an SCM will greatly help the team manage changes. Further, Hunt and Thomas [HT 00] suggest that even an individual should use an SCM to manage their work, even if their team does not, because of its ability to archive work and to "undo" mistakes.
• Commit code changes frequently: Much of the advice suggests that source code should be integrated on a regular basis, some even suggesting checking-in code every few hours.
• In a Lock-Modify-Unlock model, check-out only what you need: This advice is probably obvious, but in the Lock-Modify-Unlock model, source files will be unavailable for others to update in the Lock phase, so keeping that number of files to a minimum reduces programming team "deadlocks". For development teams that have the maturity or tooling, a Change-Modify-Merge model reduces the concern about reserving files, but does not eliminate the potential issues (in particular, dealing with merge conflicts).
• Store tooling as well as source code in the SCM: Actually, much advice suggests storing even more artifacts, but in particular, if a software team wants to recreate a specific version of the software, it will likely be crucial to have access to the original tools that created that version, as well as the source code. See section 6 of the white paper High-level Best Practices in Software Configuration Management by Laura Wingerd and Christopher Seiwald at Perforce Software. As a corollary to this item, generated code (object files, executable results of builds, etc.) should not be stored in the SCM repository.
• Create meaningful comments when committing files: By writing descriptive comments about a check-in, it will be easier for someone in the future to understand the rationale behind a change.
• Branch only when needed: The white paper mentioned previously speaks most to this point in its section 4, but it is also mentioned in other places. In particular, when more than one version of a software product is being developed concurrently, especially when the rules for checking out and committing source files may be different between the multiple version, branching is necessary to help the development team manage their project effectively.

Conclusion

SCMs provide a valuable tool for helping software developers manage change in a software project. Following some of the recommendations presented, a software development team can gain the most effectiveness from the use of SCMs.

References

These links and resources can help the reader further understand the need for source code control:

• http://oreilly.com/catalog/practicalperforce/chapter/ch07.pdf, pp. 176-178.
• Dart, S. “Spectrum of Functionality in Configuration Management Systems", Software Engineering Institute, 1990. Review pp. 1-4.
• http://svnbook.red-bean.com/en/1.4/svn-book.html, review the Forward section.
• A Visual Guide to Version Control. Review the section titled “So Why Do We Need A Version Control System (VCS)?”
• Pressman, Roger S., Software Engineering: A Practitioner’s Approach, pp. 739-742, McGraw-Hill, New York, NY, 2005

These links can provide the reader with additional information on SCM vocabulary:

• Developing with Source Code Control - Best Practices Part 2: Review the Vocabulary section.
• A Visual Guide to Version Control: Review the Learn the Lingo section.
• Revision Control in Wikipedia. Review the Common Vocabulary section.

Review these references for additional information on SCM best practices:

• http://msmvps.com/blogs/peterritchie/archive/2008/10/18/developing-with-source-code-control-best-practices-part-1.aspx
• http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx
• http://www.perforce.com/perforce/papers/bestpractices.html
• http://msdn.microsoft.com/en-us/library/ee371247%28Expression.30%29.aspx
• http://books.google.com/books?id=-2wqcKAq4tIC&pg=PA45&lpg=PA45&dq=source+code+control+best+practices
• http://www.martinfowler.com/articles/continuousIntegration.html