Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Fall 2009/wiki2 7 co

2009-10-10T00:42:17Z

Jlmatloc:

== Code Reuse Methods and Mechanisms ==

''The best way to attack the essence of building software is not to build it at all.''
- [http://en.wikipedia.org/wiki/Fred_Brooks Fredrick P. Brooks, Jr.],''[http://en.wikipedia.org/wiki/The_Mythical_Man-Month The Mythical Man-Month]''

In his 1975 classic, ''[http://en.wikipedia.org/wiki/The_Mythical_Man-Month The Mythical Man-Month]'', [http://en.wikipedia.org/wiki/Fred_Brooks Fred Brooks] claimed that the implementation of design (what he called "accidental tasks") was essentially efficient enough that improvements in that area would not result in significant gains in productivity. Twenty years later, in a follow-up edition, he refined and clarified his view. He recognized that the rise of object-oriented languages and methodologies had the potential and promise of easy reuse, although he was still skeptical of dramatic productivity claims. Fundamentally, though, he saw that overall software development productivity can be enhanced through reuse.

This page will review some of the different techniques that are available for code reuse, and then a comparison of the techniques will be presented.

== Code Reuse Through Direct Code Use ==

There are several classic code reuse mechanisms which work at the fundamental source code level. This section will discuss this class of mechanisms.

=== Cut & Paste ===

One of the most basic reuse mechanism is the cut and paste method. Simply find the source code that performs the function that is required and copy the code into the place it is needed. This method can be implemented either by copying from some external source, such as a book or another software program, or by duplicating the same code within the same program. The latter method is generally a [http://sourcemaking.com/antipatterns/cut-and-paste-programming very discouraged practice]. Additionally, using this method can lead to [http://en.wikipedia.org/wiki/Copy_and_paste_programming plagiarism].

=== Includes ===

In C and C++, the '''includes''' construct places the contents of the file specified in the include parameter in the spot where the include is placed:

#include "time.h"

class Time
{...

In this example, the compiler effectively copies the code within time.h at the point where the #include statement is declared. Nearly all compilers will provide for specifying paths to search for the indicated file and provide rules or conventions for dealing with multiple occurrences of the same file.

== Code Reuse through Subroutines ==

This section explores code reuse mechanisms that involve executing common blocks of code that can provide utility or common operations.

=== Gosub ===

In [http://www.vintage-basic.net/ Vintage Basic] (comparable to the Basic language dialects from the late 70s and early 80s), individual lines of code are designated by line numbers. Blocks of code can be designated as subroutines and the '''GOSUB''' command can jump to these blocks of code. Execution jumps back to the line following the GOSUB command once a '''RETURN''' is encountered in the subroutine:

10 FOR I=1 TO 5
20 GOSUB 100
30 NEXT I
40 END
100 PRINT "Value = "; I
110 RETURN

Note that in this construct, parameters are not passed to the subroutine, but since all variables were global, parameters could still be simulated through careful use of global variables.

=== Procedures ===

In Pascal, '''procedures''' provided a way to jump to a block of code, and parameters can be passed to that block as well:

var j:Integer;

procedure PrintValue(i: Integer);
begin
Write("Value = ");
Writeln(i);
end;

begin
for j := 1 to 5 do
PrintValue(j)
end.

In this scheme, in order to update parameters with actions performed within the procedure, a parameter must be [http://www.arl.wustl.edu/~lockwood/class/cs306/books/artofasm/Chapter_11/CH11-2.html#HEADING2-29 '''passed by reference'''], effectively passing the memory address of the parameter so it can be effected directly.

=== Functions ===

Pascal also includes a construct called '''functions''' which allow a subroutine to return a value to the caller:

var j:Integer;

function Square(i: Integer): Integer;
begin
Square = i * i;
end;

begin
for j := 1 to 5 do
Writeln("Square of ", j, " = ", Square(j));
end.

Although a similar construct can be created using procedures, functions allow for more concise coding.

== Code Reuse through Extension ==

Many languages allow existing code to be reused through extensions that leave the original code unaltered. This section explores those mechanisms.

=== Methods ===

'''Methods''' (in [http://java.sun.com/docs/books/tutorial/java/javaOO/methods.html Java] and [http://www.cplusplus.com/doc/tutorial/classes/ C++]) are functions which are encapsulated within a class structure. The class structure can provide a level of data and implementation hiding which can facilitate better design.

public class Square {
...
public void draw(String s) {
...
}
}

In and of themselves, methods do not offer any additional capability over functions, but operating within a class structure, several object-oriented paradigms can make methods more effective for code reuse.

=== Inheritance ===

'''Inheritance''' is an object-oriented concept which allows a developer to create subclasses of a base class which can refine or expand the base class.

Example needed

Using inheritance, base classes can hold much of the common elements that are used by the subclasses, thus code is reused by the subclasses through the common base class.

=== Polymorphism ===

'''Polymorphism''' is another object-oriented concept which allows a developer to reuse a defined interface in a class, but provide for an implementation that is specialized to that specific class.

abstract public class Shape {
abstract public void draw();
}

public class Square extends Shape {
public draw() {
...
}
}

public class Circle extends Shape {
public draw() {
...
}
}

In this example, the draw method has been indicated in the Shape class, but implemented in the subclasses Square and Circle. This example may not seem like code reuse, but it can be argued that the concept around providing a common signature for the subclasses is a type of reuse. Further, polymorphism provides one of the key foundations for object-oriented programming.

=== Generics ===

'''Generics''' in Java and C++ provide a mechanism where a type or class (such as String, int, or Shape) can be provided to a method as a parameter. In this fashion, the generic method can accommodate multiple types, or they can be used to catch potential typing issues at compile time that might otherwise be missed.

* [http://java.sun.com/docs/books/tutorial/extra/generics/index.html Tutorial on Generics in Java]
* [http://msdn.microsoft.com/en-us/library/c570k3f3%28VS.80%29.aspx Overview of Generics in Visual C++]

=== Mixins/Modules ===

Text and Example needed

=== Aspect ===

Text and Example needed

== Comparing the Various Mechanisms ==

Comparison table needed

== Why Reuse Is Not Always Embraced ==

With all the various techniques available, code reuse is not universally embraced, either academically or commercially. What are the reasons for not reusing existing code?

* '''Speed''' - explain
* '''Lack of documentation''' - explain
* '''Complexity''' - explain
* '''Poor Design''' - explain
* '''Licensing Issues''' - explain
* '''Lack of Trust/Fear''' - explain

== Conclusion ==

Conclusion needed

== References ==

* Brooks, Jr., F.P. ''[http://en.wikipedia.org/wiki/The_Mythical_Man-Month The Mythical Man-Month]''. Boston, MA: Addison Wesley Longman, Inc., 1995.
* [http://sourcemaking.com/antipatterns/cut-and-paste-programming Cut-and-Paste Programming]

CSC/ECE 517 Fall 2009/wiki2 7 co

2009-10-10T00:38:44Z

Jlmatloc:

== Code Reuse Methods and Mechanisms ==

''The best way to attack the essence of building software is not to build it at all.''
- [http://en.wikipedia.org/wiki/Fred_Brooks Fredrick P. Brooks, Jr.],''[http://en.wikipedia.org/wiki/The_Mythical_Man-Month The Mythical Man-Month]''

In his 1975 classic, ''[http://en.wikipedia.org/wiki/The_Mythical_Man-Month The Mythical Man-Month]'', [http://en.wikipedia.org/wiki/Fred_Brooks Fred Brooks] claimed that the implementation of design (what he called "accidental tasks") was essentially efficient enough that improvements in that area would not result in significant gains in productivity. Twenty years later, in a follow-up edition, he refined and clarified his view. He recognized that the rise of object-oriented languages and methodologies had the potential and promise of easy reuse, although he was still skeptical of dramatic productivity claims. Fundamentally, though, he saw that overall software development productivity can be enhanced through reuse.

This page will review some of the different techniques that are available for code reuse, and then a comparison of the techniques will be presented.

== Code Reuse Through Direct Code Use ==

There are several classic code reuse mechanisms which work at the fundamental source code level. This section will discuss this class of mechanisms.

=== Cut & Paste ===

One of the most basic reuse mechanism is the cut and paste method. Simply find the source code that performs the function that is required and copy the code into the place it is needed. This method can be implemented either by copying from some external source, such as a book or another software program, or by duplicating the same code within the same program. The latter method is generally a [http://sourcemaking.com/antipatterns/cut-and-paste-programming very discouraged practice]. Additionally, using this method can lead to [http://en.wikipedia.org/wiki/Copy_and_paste_programming plagiarism].

=== Includes ===

In C and C++, the '''includes''' construct places the contents of the file specified in the include parameter in the spot where the include is placed:

#include "time.h"

class Time
{...

In this example, the compiler effectively copies the code within time.h at the point where the #include statement is declared. Nearly all compilers will provide for specifying paths to search for the indicated file and provide rules or conventions for dealing with multiple occurrences of the same file.

== Code Reuse through Subroutines ==

This section explores code reuse mechanisms that involve executing common blocks of code that can provide utility or common operations.

=== Gosub ===

In [http://www.vintage-basic.net/ Vintage Basic] (comparable to the Basic language dialects from the late 70s and early 80s), individual lines of code are designated by line numbers. Blocks of code can be designated as subroutines and the '''GOSUB''' command can jump to these blocks of code. Execution jumps back to the line following the GOSUB command once a '''RETURN''' is encountered in the subroutine:

10 FOR I=1 TO 5
20 GOSUB 100
30 NEXT I
40 END
100 PRINT "Value = "; I
110 RETURN

Note that in this construct, parameters are not passed to the subroutine, but since all variables were global, parameters could still be simulated through careful use of global variables.

=== Procedures ===

In Pascal, '''procedures''' provided a way to jump to a block of code, and parameters can be passed to that block as well:

var j:Integer;

procedure PrintValue(i: Integer);
begin
Write("Value = ");
Writeln(i);
end;

begin
for j := 1 to 5 do
PrintValue(j)
end.

In this scheme, in order to update parameters with actions performed within the procedure, a parameter must be [http://www.arl.wustl.edu/~lockwood/class/cs306/books/artofasm/Chapter_11/CH11-2.html#HEADING2-29 '''passed by reference'''], effectively passing the memory address of the parameter so it can be effected directly.

=== Functions ===

Pascal also includes a construct called '''functions''' which allow a subroutine to return a value to the caller:

var j:Integer;

function Square(i: Integer): Integer;
begin
Square = i * i;
end;

begin
for j := 1 to 5 do
Writeln("Square of ", j, " = ", Square(j));
end.

Although a similar construct can be created using procedures, functions allow for more concise coding.

== Code Reuse through Extension ==

Many languages allow existing code to be reused through extensions that leave the original code unaltered. This section explores those mechanisms.

=== Methods ===

'''Methods''' (in [http://java.sun.com/docs/books/tutorial/java/javaOO/methods.html Java] and [http://www.cplusplus.com/doc/tutorial/classes/ C++]) are functions which are encapsulated within a class structure. The class structure can provide a level of data and implementation hiding which can facilitate better design.

public class Square {
...
public void draw(String s) {
...
}
}

In and of themselves, methods do not offer any additional capability over functions, but operating within a class structure, several object-oriented paradigms can make methods more effective for code reuse.

=== Inheritance ===

'''Inheritance''' is an object-oriented concept which allows a developer to create subclasses of a base class which can refine or expand the base class.

Example

Using inheritance, base classes can hold much of the common elements that are used by the subclasses, thus code is reused by the subclasses through the common base class.

=== Polymorphism ===

'''Polymorphism''' is another object-oriented concept which allows a developer to reuse a defined interface in a class, but provide for an implementation that is specialized to that specific class.

abstract public class Shape {
abstract public void draw();
}

public class Square extends Shape {
public draw() {
...
}
}

public class Circle extends Shape {
public draw() {
...
}
}

In this example, the draw method has been indicated in the Shape class, but implemented in the subclasses Square and Circle. This example may not seem like code reuse, but it can be argued that the concept around providing a common signature for the subclasses is a type of reuse. Further, polymorphism provides one of the key foundations for object-oriented programming.

=== Generics ===

'''Generics''' in Java and C++ provide a mechanism where a type or class (such as String, int, or Shape) can be provided to a method as a parameter. In this fashion, the generic method can accommodate multiple types, or they can be used to catch potential typing issues at compile time that might otherwise be missed.

* [http://java.sun.com/docs/books/tutorial/extra/generics/index.html Tutorial on Generics in Java]
* [http://msdn.microsoft.com/en-us/library/c570k3f3%28VS.80%29.aspx Overview of Generics in Visual C++]

=== Mixins/Modules ===

blah

=== Aspect ===

blah

== Comparing the Various Mechanisms ==

== Why Reuse Is Not Always Embraced ==

With all the various techniques available, code reuse is not universally embraced, either academically or commercially. What are the reasons for not reusing existing code?

* '''Speed''' -
* '''Lack of documentation''' -
* '''Complexity''' -
* '''Poor Design''' -
* '''Licensing Issues''' -
* '''Lack of Trust/Fear''' -

== Conclusion ==
blah!

== References ==

* Brooks, Jr., F.P. ''[http://en.wikipedia.org/wiki/The_Mythical_Man-Month The Mythical Man-Month]''. Boston, MA: Addison Wesley Longman, Inc., 1995.
* [http://sourcemaking.com/antipatterns/cut-and-paste-programming Cut-and-Paste Programming]

CSC/ECE 517 Fall 2009/wiki2 7 co

2009-10-09T23:21:26Z

Jlmatloc:

== Code Reuse Methods and Mechanisms ==

''The best way to attack the essence of building software is not to build it at all.''
- [http://en.wikipedia.org/wiki/Fred_Brooks Fredrick P. Brooks, Jr.],''[http://en.wikipedia.org/wiki/The_Mythical_Man-Month The Mythical Man-Month]''

In his 1975 classic, ''[http://en.wikipedia.org/wiki/The_Mythical_Man-Month The Mythical Man-Month]'', [http://en.wikipedia.org/wiki/Fred_Brooks Fred Brooks] claimed that the implementation of design (what he called "accidental tasks") was essentially efficient enough that improvements in that area would not result in significant gains in productivity. Twenty years later, in a follow-up edition, he refined and clarified his view. He recognized that the rise of object-oriented languages and methodologies had the potential and promise of easy reuse, although he was still skeptical of dramatic productivity claims. Fundamentally, though, he saw that overall software development productivity can be enhanced through reuse.

This page will review some of the different techniques that are available for code reuse, and then a comparison of the techniques will be presented.

== Code Reuse Through Direct Code Use ==

There are several classic code reuse mechanisms which work at the fundamental source code level. This section will discuss this class of mechanisms.

=== Cut & Paste ===

One of the most basic reuse mechanism is the cut and paste method. Simply find the source code that performs the function that is required and copy the code into the place it is needed. This method can be implemented either by copying from some external source, such as a book or another software program, or by duplicating the same code within the same program. The latter method is generally a [http://sourcemaking.com/antipatterns/cut-and-paste-programming | very discouraged practice]. Additionally, using this method can lead to [http://en.wikipedia.org/wiki/Copy_and_paste_programming | plagiarism].

=== Includes ===

In C and C++, the '''includes''' construct places the contents of the file specified in the include parameter in the spot where the include is placed:

#include "time.h"

class Time
{...

In this example, the compiler effectively copies the code within time.h at the point where the #include statement is declared. Nearly all compilers will provide for specifying paths to search for the indicated file and provide rules or conventions for dealing with multiple occurrences of the same file.

== Code Reuse through Subroutines ==

This section explores code reuse mechanisms that involve executing common blocks of code that can provide utility or common operations.

=== Gosub ===

In [http://www.vintage-basic.net/ | Vintage Basic] (comparable to the Basic language dialects from the late 70s and early 80s), individual lines of code are designated by line numbers. Blocks of code can be designated as subroutines and the '''GOSUB''' command can jump to these blocks of code. Execution jumps back to the line following the GOSUB command once a '''RETURN''' is encountered in the subroutine:

10 FOR I=1 TO 5
20 GOSUB 100
30 NEXT I
40 END
100 PRINT "Value = "; I
110 RETURN

Note that in this construct, parameters are not passed to the subroutine, but since all variables were global, parameters could still be simulated through careful use of global variables.

=== Procedures ===

In Pascal, '''procedures''' provided a way to jump to a block of code, and parameters can be passed to that block as well:

var j:Integer;

procedure PrintValue(i: Integer);
begin
Write("Value = ");
Writeln(i);
end;

begin
for j := 1 to 5 do
PrintValue(j)
end.

In this scheme, in order to update parameters with actions performed within the procedure, a parameter must be [http://www.arl.wustl.edu/~lockwood/class/cs306/books/artofasm/Chapter_11/CH11-2.html#HEADING2-29 | '''passed by reference'''], effectively passing the memory address of the parameter so it can be effected directly.

=== Functions ===

Pascal also includes a construct called '''functions''' which allow a subroutine to return a value to the caller:

var j:Integer;

function Square(i: Integer): Integer;
begin
Square = i * i;
end;

begin
for j := 1 to 5 do
Writeln("Square of ", j, " = ", Square(j));
end.

Although a similar construct can be created using procedures, functions allow for more concise coding.

== Code Reuse through Extension ==

Many languages allow existing code to be reused through extensions that leave the original code unaltered. This section explores those mechanisms.

=== Methods ===

blah

=== Inheritance ===

blah

=== Polymorphism ===

blah

=== Generics ===

blah

=== Mixins/Modules ===

blah

=== Aspect ===

blah

== Comparing the Various Mechanisms ==

== Why Reuse Is Not Always Embraced ==

With all the various techniques available, code reuse is not universally embraced, either academically or commercially. What are the reasons for not reusing existing code?

* '''Speed''' -
* '''Lack of documentation''' -
* '''Complexity''' -
* '''Poor Design''' -
* '''Licensing Issues''' -
* '''Lack of Trust/Fear''' -

== Conclusion ==
blah!

== References ==

* Brooks, Jr., F.P. ''[http://en.wikipedia.org/wiki/The_Mythical_Man-Month The Mythical Man-Month]''. Boston, MA: Addison Wesley Longman, Inc., 1995.
* [http://sourcemaking.com/antipatterns/cut-and-paste-programming | Cut-and-Paste Programming]

CSC/ECE 517 Fall 2009/wiki2 7 co

2009-10-09T22:46:45Z

Jlmatloc:

CSC/ECE 517 Fall 2009/wiki2 7 co

2009-10-09T22:42:22Z

Jlmatloc:

CSC/ECE 517 Fall 2009/wiki2 7 co

2009-10-09T22:01:41Z

Jlmatloc:

CSC/ECE 517 Fall 2009/wiki2 7 co

2009-10-09T21:57:01Z

Jlmatloc:

CSC/ECE 517 Fall 2009/wiki2 7 co

2009-10-09T18:59:03Z

Jlmatloc:

CSC/ECE 517 Fall 2009/wiki2 7 co

2009-10-09T02:31:32Z

Jlmatloc:

CSC/ECE 517 Fall 2009/wiki2 7 co

2009-10-09T02:31:10Z

Jlmatloc:

CSC/ECE 517 Fall 2009/wiki2 7 co

2009-10-09T02:30:48Z

Jlmatloc:

CSC/ECE 517 Fall 2009/wiki2 7 co

2009-10-08T23:55:35Z

Jlmatloc: Initial edit with outline

CSC/ECE 517 Fall 2009/wiki2 7 co

2009-10-05T01:40:58Z

Jlmatloc:

= Code Reuse Mechanisms =

Different languages have different mechanisms for "code reuse". Assembly and low level languages have macros, C/C++ has includes, Ruby has mixins and modules, Java has packages, and there are many other concepts around reuse and extension. Write a page that describes the various mechanisms, group the mechanisms into logical categories, and discuss the advantages and disadvantages of the various schemes, in terms of simplicity, performance, reliability, or other factors.

== Code Reuse ==
* Cut & Paste
* Macros
* Functions/Methods
* Includes
* Libraries
* Packages
* Inheritance
* Polymorphism
* Generics
* Mixins/Modules
* Aspect
* Patterns

== Reasons Not to Reuse ==
* Speed
* Lack of documentation
* Complexity
* Poor Design
* Lack of Trust/Fear

CSC/ECE 517 Fall 2009/wiki1a 4 co

2009-09-17T00:31:51Z

Jlmatloc: /* Why Source Code Control is Necessary */

== 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 ==

Pressman suggests four primary reasons for change [P 05]:
* 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
* [http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.basic.vsn-models.lock-unlock.dia-1 '''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.
* [http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.basic.vsn-models.copy-merge.dia-1 '''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.

----

[[Image:SCM-Lock-Modify-Unlock.png|Two developers using a Lock-Modify-Unlock modeling SCM]]

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.

----

[[Image:SCM-Change-Modify-Merge1.png|Two developers using a Change-Modify-Merge modeling SCM, Checking-out]]

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.

----

[[Image:SCM-Change-Modify-Merge2.png|Two developers using a Change-Modify-Merge modeling SCM, First check-in]]

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

----

[[Image:SCM-Change-Modify-Merge3.png|Two developers using a Change-Modify-Merge modeling SCM, Second check-in]]

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 [http://www.martinfowler.com/articles/continuousIntegration.html integrated on a regular basis], some even suggesting [http://www.extremeprogramming.org/rules/integrateoften.html checking-in code every few hours].
* '''In a Lock-Modify-Unlock model, check-out only what you need:''' [http://msdn.microsoft.com/en-us/library/ee371247%28Expression.30%29.aspx 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 [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx merge conflicts]).
* '''Store tooling as well as source code in the SCM:''' Actually, much advice suggests storing [http://books.google.com/books?id=-2wqcKAq4tIC&pg=PA45&lpg=PA45&dq=source+code+control+best+practices 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 [http://www.perforce.com/perforce/papers/bestpractices.html High-level Best Practices in Software Configuration Management] by Laura Wingerd and Christopher Seiwald at Perforce Software. As a corollary to this item, [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx 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 [http://www.perforce.com/perforce/papers/bestpractices.html white paper] mentioned previously speaks most to this point in its section 4, but it is also mentioned in [http://books.google.com/books?id=-2wqcKAq4tIC&pg=PA45&lpg=PA45&dq=source+code+control+best+practices 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. [http://www.sei.cmu.edu/reports/90tr011.pdf “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.
* [http://betterexplained.com/articles/a-visual-guide-to-version-control/ 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:

* [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx Developing with Source Code Control - Best Practices Part 2]: Review the '''Vocabulary''' section.
* [http://betterexplained.com/articles/a-visual-guide-to-version-control/ A Visual Guide to Version Control]: Review the '''Learn the Lingo''' section.
* [http://en.wikipedia.org/wiki/Source_Code_Management#Common_vocabulary 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

CSC/ECE 517 Fall 2009/wiki1a 4 co

2009-09-17T00:29:38Z

Jlmatloc: /* Understanding the Two Models */

== 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
* [http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.basic.vsn-models.lock-unlock.dia-1 '''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.
* [http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.basic.vsn-models.copy-merge.dia-1 '''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.

----

[[Image:SCM-Lock-Modify-Unlock.png|Two developers using a Lock-Modify-Unlock modeling SCM]]

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.

----

[[Image:SCM-Change-Modify-Merge1.png|Two developers using a Change-Modify-Merge modeling SCM, Checking-out]]

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.

----

[[Image:SCM-Change-Modify-Merge2.png|Two developers using a Change-Modify-Merge modeling SCM, First check-in]]

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

----

[[Image:SCM-Change-Modify-Merge3.png|Two developers using a Change-Modify-Merge modeling SCM, Second check-in]]

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 [http://www.martinfowler.com/articles/continuousIntegration.html integrated on a regular basis], some even suggesting [http://www.extremeprogramming.org/rules/integrateoften.html checking-in code every few hours].
* '''In a Lock-Modify-Unlock model, check-out only what you need:''' [http://msdn.microsoft.com/en-us/library/ee371247%28Expression.30%29.aspx 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 [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx merge conflicts]).
* '''Store tooling as well as source code in the SCM:''' Actually, much advice suggests storing [http://books.google.com/books?id=-2wqcKAq4tIC&pg=PA45&lpg=PA45&dq=source+code+control+best+practices 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 [http://www.perforce.com/perforce/papers/bestpractices.html High-level Best Practices in Software Configuration Management] by Laura Wingerd and Christopher Seiwald at Perforce Software. As a corollary to this item, [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx 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 [http://www.perforce.com/perforce/papers/bestpractices.html white paper] mentioned previously speaks most to this point in its section 4, but it is also mentioned in [http://books.google.com/books?id=-2wqcKAq4tIC&pg=PA45&lpg=PA45&dq=source+code+control+best+practices 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. [http://www.sei.cmu.edu/reports/90tr011.pdf “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.
* [http://betterexplained.com/articles/a-visual-guide-to-version-control/ 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:

* [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx Developing with Source Code Control - Best Practices Part 2]: Review the '''Vocabulary''' section.
* [http://betterexplained.com/articles/a-visual-guide-to-version-control/ A Visual Guide to Version Control]: Review the '''Learn the Lingo''' section.
* [http://en.wikipedia.org/wiki/Source_Code_Management#Common_vocabulary 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

CSC/ECE 517 Fall 2009/wiki1a 4 co

2009-09-17T00:27:55Z

Jlmatloc: /* Understanding Basic Concepts */

== 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
* [http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.basic.vsn-models.lock-unlock.dia-1 '''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.
* [http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.basic.vsn-models.copy-merge.dia-1 '''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.

[[Image:SCM-Lock-Modify-Unlock.png|Two developers using a Lock-Modify-Unlock modeling SCM]]

----

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.

[[Image:SCM-Change-Modify-Merge1.png|Two developers using a Change-Modify-Merge modeling SCM, Checking-out]]
----

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

[[Image:SCM-Change-Modify-Merge2.png|Two developers using a Change-Modify-Merge modeling SCM, First check-in]]
----

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.

[[Image:SCM-Change-Modify-Merge3.png|Two developers using a Change-Modify-Merge modeling SCM, Second check-in]]
----

== 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 [http://www.martinfowler.com/articles/continuousIntegration.html integrated on a regular basis], some even suggesting [http://www.extremeprogramming.org/rules/integrateoften.html checking-in code every few hours].
* '''In a Lock-Modify-Unlock model, check-out only what you need:''' [http://msdn.microsoft.com/en-us/library/ee371247%28Expression.30%29.aspx 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 [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx merge conflicts]).
* '''Store tooling as well as source code in the SCM:''' Actually, much advice suggests storing [http://books.google.com/books?id=-2wqcKAq4tIC&pg=PA45&lpg=PA45&dq=source+code+control+best+practices 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 [http://www.perforce.com/perforce/papers/bestpractices.html High-level Best Practices in Software Configuration Management] by Laura Wingerd and Christopher Seiwald at Perforce Software. As a corollary to this item, [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx 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 [http://www.perforce.com/perforce/papers/bestpractices.html white paper] mentioned previously speaks most to this point in its section 4, but it is also mentioned in [http://books.google.com/books?id=-2wqcKAq4tIC&pg=PA45&lpg=PA45&dq=source+code+control+best+practices 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. [http://www.sei.cmu.edu/reports/90tr011.pdf “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.
* [http://betterexplained.com/articles/a-visual-guide-to-version-control/ 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:

* [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx Developing with Source Code Control - Best Practices Part 2]: Review the '''Vocabulary''' section.
* [http://betterexplained.com/articles/a-visual-guide-to-version-control/ A Visual Guide to Version Control]: Review the '''Learn the Lingo''' section.
* [http://en.wikipedia.org/wiki/Source_Code_Management#Common_vocabulary 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

CSC/ECE 517 Fall 2009/wiki1a 4 co

2009-09-17T00:10:01Z

Jlmatloc: /* Understanding Basic Concepts */

== 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
* [http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.basic.vsn-models.lock-unlock.dia-1 '''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.
* [http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.basic.vsn-models.copy-merge.dia-1 '''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.

[[Image:SCM-Lock-Modify-Unlock.png|Two developers using a Lock-Modify-Unlock modeling SCM]]

Text

[[Image:SCM-Change-Modify-Merge1.png|Two developers using a Change-Modify-Merge modeling SCM, Checking-out]]

Text

[[Image:SCM-Change-Modify-Merge2.png|Two developers using a Change-Modify-Merge modeling SCM, First check-in]]

Text

[[Image:SCM-Change-Modify-Merge3.png|Two developers using a Change-Modify-Merge modeling SCM, Second check-in]]

Text

== 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 [http://www.martinfowler.com/articles/continuousIntegration.html integrated on a regular basis], some even suggesting [http://www.extremeprogramming.org/rules/integrateoften.html checking-in code every few hours].
* '''In a Lock-Modify-Unlock model, check-out only what you need:''' [http://msdn.microsoft.com/en-us/library/ee371247%28Expression.30%29.aspx 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 [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx merge conflicts]).
* '''Store tooling as well as source code in the SCM:''' Actually, much advice suggests storing [http://books.google.com/books?id=-2wqcKAq4tIC&pg=PA45&lpg=PA45&dq=source+code+control+best+practices 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 [http://www.perforce.com/perforce/papers/bestpractices.html High-level Best Practices in Software Configuration Management] by Laura Wingerd and Christopher Seiwald at Perforce Software. As a corollary to this item, [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx 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 [http://www.perforce.com/perforce/papers/bestpractices.html white paper] mentioned previously speaks most to this point in its section 4, but it is also mentioned in [http://books.google.com/books?id=-2wqcKAq4tIC&pg=PA45&lpg=PA45&dq=source+code+control+best+practices 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. [http://www.sei.cmu.edu/reports/90tr011.pdf “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.
* [http://betterexplained.com/articles/a-visual-guide-to-version-control/ 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:

* [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx Developing with Source Code Control - Best Practices Part 2]: Review the '''Vocabulary''' section.
* [http://betterexplained.com/articles/a-visual-guide-to-version-control/ A Visual Guide to Version Control]: Review the '''Learn the Lingo''' section.
* [http://en.wikipedia.org/wiki/Source_Code_Management#Common_vocabulary 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

File:SCM-Change-Modify-Merge3.png

2009-09-17T00:04:15Z

Jlmatloc: Two developers working with a Change-Modify-Merge modeling SCM (3 of 3).

Two developers working with a Change-Modify-Merge modeling SCM (3 of 3).

File:SCM-Change-Modify-Merge2.png

2009-09-17T00:04:05Z

Jlmatloc: Two developers working with a Change-Modify-Merge modeling SCM (2 of 3).

Two developers working with a Change-Modify-Merge modeling SCM (2 of 3).

File:SCM-Change-Modify-Merge1.png

2009-09-17T00:03:52Z

Jlmatloc: Two developers working with a Change-Modify-Merge modeling SCM (1 of 3).

Two developers working with a Change-Modify-Merge modeling SCM (1 of 3).

File:SCM-Lock-Modify-Unlock.png

2009-09-17T00:03:18Z

Jlmatloc: Two developers working with a Lock-Modify-Unlock modeling SCM.

Two developers working with a Lock-Modify-Unlock modeling SCM.

CSC/ECE 517 Fall 2009/wiki1a 4 co

2009-09-17T00:01:46Z

Jlmatloc: /* Understanding Basic Concepts */

== 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
* [http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.basic.vsn-models.lock-unlock.dia-1 '''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.
* [http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.basic.vsn-models.copy-merge.dia-1 '''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.

== 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 [http://www.martinfowler.com/articles/continuousIntegration.html integrated on a regular basis], some even suggesting [http://www.extremeprogramming.org/rules/integrateoften.html checking-in code every few hours].
* '''In a Lock-Modify-Unlock model, check-out only what you need:''' [http://msdn.microsoft.com/en-us/library/ee371247%28Expression.30%29.aspx 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 [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx merge conflicts]).
* '''Store tooling as well as source code in the SCM:''' Actually, much advice suggests storing [http://books.google.com/books?id=-2wqcKAq4tIC&pg=PA45&lpg=PA45&dq=source+code+control+best+practices 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 [http://www.perforce.com/perforce/papers/bestpractices.html High-level Best Practices in Software Configuration Management] by Laura Wingerd and Christopher Seiwald at Perforce Software. As a corollary to this item, [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx 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 [http://www.perforce.com/perforce/papers/bestpractices.html white paper] mentioned previously speaks most to this point in its section 4, but it is also mentioned in [http://books.google.com/books?id=-2wqcKAq4tIC&pg=PA45&lpg=PA45&dq=source+code+control+best+practices 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. [http://www.sei.cmu.edu/reports/90tr011.pdf “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.
* [http://betterexplained.com/articles/a-visual-guide-to-version-control/ 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:

* [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx Developing with Source Code Control - Best Practices Part 2]: Review the '''Vocabulary''' section.
* [http://betterexplained.com/articles/a-visual-guide-to-version-control/ A Visual Guide to Version Control]: Review the '''Learn the Lingo''' section.
* [http://en.wikipedia.org/wiki/Source_Code_Management#Common_vocabulary 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

CSC/ECE 517 Fall 2009/wiki1a 4 co

2009-09-16T23:32:34Z

Jlmatloc:

== 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
* [http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.basic.vsn-models.lock-unlock.dia-1 '''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.
* [http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.basic.vsn-models.copy-merge.dia-1 '''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.

== 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 [http://www.martinfowler.com/articles/continuousIntegration.html integrated on a regular basis], some even suggesting [http://www.extremeprogramming.org/rules/integrateoften.html checking-in code every few hours].
* '''In a Lock-Modify-Unlock model, check-out only what you need:''' [http://msdn.microsoft.com/en-us/library/ee371247%28Expression.30%29.aspx 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 [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx merge conflicts]).
* '''Store tooling as well as source code in the SCM:''' Actually, much advice suggests storing [http://books.google.com/books?id=-2wqcKAq4tIC&pg=PA45&lpg=PA45&dq=source+code+control+best+practices 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 [http://www.perforce.com/perforce/papers/bestpractices.html High-level Best Practices in Software Configuration Management] by Laura Wingerd and Christopher Seiwald at Perforce Software. As a corollary to this item, [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx 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 [http://www.perforce.com/perforce/papers/bestpractices.html white paper] mentioned previously speaks most to this point in its section 4, but it is also mentioned in [http://books.google.com/books?id=-2wqcKAq4tIC&pg=PA45&lpg=PA45&dq=source+code+control+best+practices 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. [http://www.sei.cmu.edu/reports/90tr011.pdf “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.
* [http://betterexplained.com/articles/a-visual-guide-to-version-control/ 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:

* [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx Developing with Source Code Control - Best Practices Part 2]: Review the '''Vocabulary''' section.
* [http://betterexplained.com/articles/a-visual-guide-to-version-control/ A Visual Guide to Version Control]: Review the '''Learn the Lingo''' section.
* [http://en.wikipedia.org/wiki/Source_Code_Management#Common_vocabulary 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

CSC/ECE 517 Fall 2009/wiki1a 4 co

2009-09-12T08:17:30Z

Jlmatloc:

== 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. Managing the change with an SCM enables engineers to focus on technical work, and enables project managers to control changes which can affect project outcomes.

=== Links and Resources ===

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. [http://www.sei.cmu.edu/reports/90tr011.pdf “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.
* [http://betterexplained.com/articles/a-visual-guide-to-version-control/ 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

== 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
* [http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.basic.vsn-models.lock-unlock.dia-1 '''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.
* [http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.basic.vsn-models.copy-merge.dia-1 '''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.

=== Links and Resources ===

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

* [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx Developing with Source Code Control - Best Practices Part 2]: Review the '''Vocabulary''' section.
* [http://betterexplained.com/articles/a-visual-guide-to-version-control/ A Visual Guide to Version Control]: Review the '''Learn the Lingo''' section.
* [http://en.wikipedia.org/wiki/Source_Code_Management#Common_vocabulary Revision Control] in Wikipedia. Review the '''Common Vocabulary''' section.

== 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 [http://www.martinfowler.com/articles/continuousIntegration.html integrated on a regular basis], some even suggesting [http://www.extremeprogramming.org/rules/integrateoften.html checking-in code every few hours].
* '''In a Lock-Modify-Unlock model, check-out only what you need:''' [http://msdn.microsoft.com/en-us/library/ee371247%28Expression.30%29.aspx 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 [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx merge conflicts]).
* '''Store tooling as well as source code in the SCM:''' Actually, much advice suggests storing [http://books.google.com/books?id=-2wqcKAq4tIC&pg=PA45&lpg=PA45&dq=source+code+control+best+practices 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 [http://www.perforce.com/perforce/papers/bestpractices.html High-level Best Practices in Software Configuration Management] by Laura Wingerd and Christopher Seiwald at Perforce Software. As a corollary to this item, [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx 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 [http://www.perforce.com/perforce/papers/bestpractices.html white paper] mentioned previously speaks most to this point in its section 4, but it is also mentioned in [http://books.google.com/books?id=-2wqcKAq4tIC&pg=PA45&lpg=PA45&dq=source+code+control+best+practices 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.

=== Links and Resources ===

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

== 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.

== All References ==

* http://oreilly.com/catalog/practicalperforce/chapter/ch07.pdf
* 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://www.ericsink.com/scm/source_control.html
* http://svnbook.red-bean.com/en/1.4/svn-book.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://en.wikipedia.org/wiki/Source_Code_Management
* http://betterexplained.com/articles/a-visual-guide-to-version-control/
* http://www.martinfowler.com/articles/continuousIntegration.html
* [P 05] Pressman, Roger S., Software Engineering: A Practitioner’s Approach, pp. 739-768, McGraw-Hill, New York, NY, 2005
* [HT 00] Hunt A. and Thomas D., The Pragmatic Programmer: From Journeyman to Master, pp. 86-89, Addison-Wesley, Boston, MA, 2000
* [D 90] Dart, S. [http://www.sei.cmu.edu/reports/90tr011.pdf “Spectrum of Functionality in Configuration Management Systems"], Software Engineering Institute, 1990.

CSC/ECE 517 Fall 2009/wiki1a 4 co

2009-09-12T08:17:09Z

Jlmatloc:

== 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. Managing the change with an SCM enables engineers to focus on technical work, and enables project managers to control changes which can affect project outcomes.

=== Links and Resources ===

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. [http://www.sei.cmu.edu/reports/90tr011.pdf “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.
* [http://betterexplained.com/articles/a-visual-guide-to-version-control/ 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

== 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
* [http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.basic.vsn-models.lock-unlock.dia-1 '''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.
* [http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.basic.vsn-models.copy-merge.dia-1 '''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.

=== Links and Resources ===

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

* [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx Developing with Source Code Control - Best Practices Part 2]: Review the '''Vocabulary''' section.
* [http://betterexplained.com/articles/a-visual-guide-to-version-control/ A Visual Guide to Version Control]: Review the '''Learn the Lingo''' section.
* [http://en.wikipedia.org/wiki/Source_Code_Management#Common_vocabulary Revision Control] in Wikipedia. Review the '''Common Vocabulary''' section.

== 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 [http://www.martinfowler.com/articles/continuousIntegration.html integrated on a regular basis], some even suggesting [http://www.extremeprogramming.org/rules/integrateoften.html checking-in code every few hours].
* '''In a Lock-Modify-Unlock model, check-out only what you need:''' [http://msdn.microsoft.com/en-us/library/ee371247%28Expression.30%29.aspx 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 [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx merge conflicts]).
* '''Store tooling as well as source code in the SCM:''' Actually, much advice suggests storing [http://books.google.com/books?id=-2wqcKAq4tIC&pg=PA45&lpg=PA45&dq=source+code+control+best+practices 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 [http://www.perforce.com/perforce/papers/bestpractices.html High-level Best Practices in Software Configuration Management] by Laura Wingerd and Christopher Seiwald at Perforce Software. As a corollary to this item, [http://msmvps.com/blogs/peterritchie/archive/2009/03/11/developing-with-source-code-control-best-practices-part-2.aspx 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 [http://www.perforce.com/perforce/papers/bestpractices.html white paper] mentioned previously speaks most to this point in its section 4, but it is also mentioned in [http://books.google.com/books?id=-2wqcKAq4tIC&pg=PA45&lpg=PA45&dq=source+code+control+best+practices 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.

=== Links and Resources ===

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

== 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.

== All References ==

* http://oreilly.com/catalog/practicalperforce/chapter/ch07.pdf
* 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://www.ericsink.com/scm/source_control.html
* http://svnbook.red-bean.com/en/1.4/svn-book.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://en.wikipedia.org/wiki/Source_Code_Management
* http://betterexplained.com/articles/a-visual-guide-to-version-control/
* http://www.martinfowler.com/articles/continuousIntegration.html
* [P 05] Pressman, Roger S., Software Engineering: A Practitioner’s Approach, pp. 739-768, McGraw-Hill, New York, NY, 2005
* [HT 00] Hunt A. and Thomas D., The Pragmatic Programmer: From Journeyman to Master, pp. 86-89, Addison-Wesley, Boston, MA, 2000
* [D 90] Dart, S. [http://www.sei.cmu.edu/reports/90tr011.pdf “Spectrum of Functionality in Configuration Management Systems"], Software Engineering Institute, 1990.

x