CSC/ECE 517 Fall 2009/wiki1a 4 SCM

Source Code Management is a mechanism to track and store the modifications made to source files during large scale software development. This is achieved by assigning a unique version number (also called revision number) for changes made to a file. Along with the version number, it also stores the username who made the changes, time-stamp and comments from the user. Version control provides a suitable environment for distributed, collaborative software development as it supports Version Comparisons, Restorations, and Merging etc.

Some of the commercial Version control systems are CVS, SVN, Git, Mercurial, Bazaar, LibreSource, Montone, Clearcase, Perforce etc.

Terminologies and Definitions

An example version control tree with basic operations

Before one understands the best practices of Source Code Management, the user must be aware of the terminologies involved. The following list provides a non-comprehensive list of terms involved in SCM.

• Repository: It is a database storing the files. This can be either distributed or centralized. In case of distributed, every user will have their own local repository copy and merging takes place peer to peer. Where as in centralized, there is only one main repository server.

• Client / Server: Computer hosting the repository is known as the server and the computer which connects to the repository is known as client.

• Workspace: The space used by the user for editing, testing, debugging and building purpose. Workspace is private copy of files. Any changes made to it is confined to the local copy which is not updated in the repository unless the user explicitly commit the changes. Workspace is also known as "Sandboxes" or "Views".

• Add: The action of putting a new file/folder into the repository for the first time. Version control starts only when files are 'Added'.

• Get: Operation of copying files from repository to workspace. The files retrieved using 'Get' are read only copies and not intended to be edited.

• Checkout: Action of Downloading a file from repository to workspace for editing. SCM maintains a list of checked out files and the username who is editing it.

• Checkin: Action of uploading the changed file to repository. SCM updates the repository my reflecting a new version of changed file.

• Version Number: Indicates the version of the specified file. Using version number we can retrieve/revert/diff to old versions of file.This feature helps to store history of changes made to the file.

• Branch: A separate private copy of file which can be used for specific purposes like testing, debugging, developing and bug fixing etc.

• Merge: Process of combining two different versions of the same file. Merging usually involves copying changes of the files present in one branch to another.

• Lock: Getting an exclusive modification rights through SCM. This means no two user can modify the same file at same time.

• History: List of changes made to a file from the time it has been added to repository. History also provide details like users who have changed the file and comments for the change.

Best practices in SCM

Workspace

• Keeping workspace in invaluable state: Working space contains a copy of files from repository. When latest version of files are copied to workspace we say that workspace is in sync with the repository. Duration between changes made to copied files and before committing the changes, the workspace is said to be in valuable mode containing latest modifications of the file. System crash during this period would result in loss of data.Hence we need to commit changes frequently in order to update repository and keep workspace in invaluable( workspace in sync with repository ) state.

• Reducing dependency on hidden state information:

• Use working folder states to keep workspace up to date : There are many states SCM displays related to files in workspace. Using these states we can make sure that workspace is always in sync with the repository.

State	Meaning
None
Old	The file in workspace is of older version when compared to the current version in the repository
Edited	File has been edited/modified in the workspace
Needs Merge	When there two different versions of same file in different branches
Missing	Working file does not exists hence need to be checked out from the repository
Renegade	Modifying a local copy of file in workspace without checking it out from the repository
Unknown	There exists a local copy of file in workspace for which SCM does not have hidden information

• Review changes before you check-in: Any changes made in workspace which has not been committed yet are displayed as "pending changes set" in the workspace. Pending changes set displays all types of changes including adds, deletes, renames, moves, and modified files. It is a good practice to keep an eye on the pending changes set so that you do not forget anything to check-in. Review changes of modified files using file diff tool provided in SCM helps to compare the latest version present in repository and working file version in the workspace.Performing review changes before check-in prevents many merge conflicts.

• Frequently updating the workspace: It can happen that after copying files to workspace some other user can modify few files and update the repository with modified changes. At this point of time the copy of files in workspace is old. It is a good practice to perform "Get Latest Version" from repository action periodically.

• Do not forget to add comments while committing changes: After the files have been modified in the workspace user has to update the repository by committing the changes. It is always good idea to write comments on what and why changes were made so that other user can insight of the latest modifications.

Check-out

Checking out a file involves tasks both at server and client side. When a file is checked out, SCM makes a note that file being checked out and person's name who is checking out with the time stamp.On the client side, it prepares the file for modification. File is enabled for modification only when it is checked out or else file will be in read only mode.When user checks out a file for modification, SCM updates the file status to be in use and does not let any other user to check out the same file. File checked out for mutual exclusive access is said to be locked.

SCM tools provide option to "undo checkout" a checked out file.SCM tool releases the lock on the file and any modifications done to the file is lost when we select "undo checkout". There are few important things that one should keep in mind while checking out a file,

• Be sure of checking out or locking a file. Because by doing so you prevent other users from modifying the file. Once file locked, other users need to wait until you release lock on the file.
• Unless there is significant change that needs to be done to a file do not check out file un-necessarily.
• Check out single file which is of your interest. Do not try checking out the entire folder where file is located.
• Checking out more files at once is not recommended. Check out few files at a time, finish task check-in and then you can check-out more files if needed.
• Confine exclusive locks to the duration of work, holding exclusive locks for longer period is not recommended.
• Keep track of files for which you own exclusive lock.Forgetting any would prevent other users from modifying those files.

Check-in

Check out, editing is followed my check-in where the changes are updated to repository. SCM tools provide a text box to write comments while checking in modified file. The comments written are permanently stored in the repository along with the changes. When a file is checked in, SCM updates the version by incrementing it by one, checkout or locked state will be removed and made available for further modifications. Similarly working copy in workspace will be made read only.

SCM tools consider any kind of changes like creating a folder, deleting a file/folder, adding file to folder, renaming/moving a file/folder as modifications that needs to be checked in to repository.

Important things that needs attention while checking in files

• Any changes should be accompanied with proper comments. Comments should explain what has been modified and why it had been modified.This is very important in large scale development as one can forget what changes were made and the reason behind the any changes. For example when a change is made to fix some bug, it is a good practice to write what bug has been fixed and a brief explanation on how it has been fixed rather than writing "Bug 12345 fixed."

• Few task may require modifications involving more than one file. It is a good to check-in all the related files of single task together.

• Restrict your self to check-in files related to one bug at a time. Checking in files related to multiple fixes makes it hard to have a one to one mapping between the bugs and files holding their fixes.