Code Co-op Tutorial

Go to Reliable Software Home Page

Code Co-op Distributed Version Control System

Functionality

Working with Projects

Creating a brand new project. When you create a new project (Select New from the Project menu), the Code Co-op creates a database where all the data about the project will be kept. What you will be seeing, is a particular directory (the root of the project) where you'll store your source files. You'll be able to access these files using your editor or a development environment. Code Co-op will make them read-only, in order to protect them from being edited without your first checking them out.
If you already have a source tree, you may create the Code Co-op project starting at the root of that tree. You'll have to add all the files and subfolders in this tree to the project.
In the New Project dialog you have to answer a few straightforward questions. You have to tell Code Co-op where to put project files on your machine. You may specify any folder--if the folder doesn't exist, co-op will create it for you. Or, you may chose a folder already populated with files, which you'll later add to project. Optionally, you may specify a separate folder for the project database--in most cases you should simply accept the default. You have to provide the project name--other members of the project will use this name to join your project. Finally, you enter your personal data--name, e-mail and phone number. This information will be later available to every member of your project (under the Members item of the Project menu).
There is an option to use short, 8.3, file names throughout the project, in case you are using a file system that imposes such limitations.
Joining an existing project. Once somebody has created a project, you may join it (Join in the Project menu). You'll have to pick a directory where the root of the project will be located on your machine. The immediate result of joining is that Code Co-op generates a special "join request" script that you'll have to e-mail to the administrator of the project. The administrator is the person who created the project in the first place (if he or she defects, the first person to join becomes the administrator, etc.). Once the administrator unpacks (synchronizes) your "join request," his Code Co-op generates a special "full-synch" script that he sends back to you. When you synchronize that script, your project tree will be populated with the exact copies of the files and folders that the administrator had in his project. As soon as you accept this synch, you may start making changes to these files.
In the Join Project dialog you have to answer a few straightforward questions. You have to tell Code Co-op where to put project files on your machine. You may specify any folder--if the folder doesn't exist, co-op will create it for you. Optionally, you may specify a separate folder for the project database--in most cases you should simply accept the default. You have to provide the project name--the same name under which the project was created in the first place. Finally, you enter your personal data--name, e-mail and phone number. This information will be later available to every member of your project (under the Members item of the Project menu).
There is an option to join a project as an Observer (a check-box in the Join Project dialog). Observers get all the synch script, but they are not allowed to modify the project, and they don't send any scripts (even the acknowledgments). Incidentally, you don't need to purchase an additional license to join a project as an observer--provided you already have one.
Defecting from a project. Sometimes a person leaves a project. He or she should do it in an orderly fashion by "defecting" (Defect in the Project menu). A special "defect script" is produced by the Code Co-op and stored directly on the person's desktop. This script should be sent to all the other members of the project.
When defecting, you get the option of preserving or deleting the whole project tree. If you chose to delete the tree, it will be moved to your recycle bin.
Visiting other projects. If you have several projects on your machine, you can switch between them using the Visit item from the Project menu. You'll see a list of projects that are available on your machine. Just double-click on one and Code Co-op will take you to it.
Branching. You can create a new project by branching it off an existing project. First, perform all the pending check-ins in your project. Then, from the Project menu select Branch. Provide the location for the new copy of the project and give it a new distinct name. Ask the members of the old project to join the new project by sending you join requests. The Branch dialog is almost identical to the New Project dialog.
Presently, there is no way to merge back two branches.
Membership changes. Every member of the project may edit his or her membership data (name, e-mail, etc.) by selecting their entry and pressing the Edit button in the Project/Members dialog box. The appropriate membership update script will be created.
Only the Administrator has the option to edit anybody's membership data. The administrator may also remove members from the project (radio button Removed from Project in the same dialog).

Working with Files

Navigating through your project. In the File Area you can navigate into a folder by double-clicking it. The name of the folder will appear in the toolbar. Going up a folder is done by clicking the Folder-Up button or by pressing Ctrl-LeftArrow. You can sort the display by clicking on the appropriate column and you can resize the columns by dragging the dividers (the sort order and column size are remembered across sessions—as is the placement and the size of the main window).
Adding an existing file or folder to the project. If a file (or a subfolder) has been created outside of the Code Co-op, you can add it to the project by selecting it and choosing Add To Project from the Selection menu. You can use multiple selections and you can use the "Add To Project" button on the toolbar. Other members of the team will learn about this addition after you make your next check-in.
Creating a new file or folder in the project. When you want to create a new file or subfolder in your project, the best way to do it is to use the facilities of the Code Co-op (New File or New Folder in the Folder menu or the New File button). The advantage of using Code Co-op to create new files is that you won't forget to check them in. They will automatically appear in your check-in area ready to be checked in.
Code Co-op keeps information about various types of files. When you create a new file, you may chose from the following types: header, source, other text or binary. For header files you have an option of creating a file initialized with the standard C (C++) preprocessor directives that prevent multiple inclusions. If you program in C or C++ we highly recommend using this feature. For both header and source files you may define your copyright notice in the form of a comment. It will be added to the file you create. Here's an example of a header file foo.h created using these options:
```
#if !defined (FOO_H)
#define FOO_H
//
// Reliable Software (c) 1998
//

#endif
```
Deleting a file. You can delete a file (deletion of folders is not implemented in this version yet) either from the menu (Delete in the Selection menu) or by clicking on the Delete button in the toolbar, or by pressing the Del key. You will still see the deleted file in the check-in area and you'll even be able to restore it (the Restore button or Restore from the Selection menu) if you change your mind before checking it in.
You also have the option to remove a file from project without deleting it (Remove from project in the Selection menu). The file will be likewise removed from the projects of all the other members, after you've send them the check-in script. It won't be physically deleted, though. Any project member can add it back, if necessary. Use this mechanism in case you inadvertently corrupted a checked-in file.
Renaming a file. Renaming is as easy as editing the file name in-place, in the File View Area. That's all. The file is automatically checked-out for you and you'll see it in the Check-in Area (of course, besides renaming it, you can also edit its contents). When you check the renamed file in, the name change, along with any other changes, will be propagated to other project members. Remember however not to rename files using other tools, even when they are checked out—Code Co-op will not be able to guess what you have done outside of it.
Moving files. Moving files is as easy as renaming. Just select the files to be moved (in the File Area of co-op) and click the cut button on the toolbar (or Ctrl-X from the keyboard). The files are now in the co-op's own clipboard. Now browse into the target folder, still in the File Area, and press the paste button (or Ctrl-V). That's it, the co-op takes care of checking the file out and propagating the move to other project members after you check it in. And, by the way, you can combine moving, renaming and editing a file in a single check-in. Again, remember not to move files using other tools, even when they are checked out—Code Co-op will not be able to guess what you have done outside of it.
Checking out a file. If you want to edit a file that's already in the project, you have to first check it out (Check-Out from the Selection menu, the Check-out button or Ctrl-O from the keyboard). It makes the file in the project tree writable; it also creates a backup of the current state of the file in the co-op's database. This backup is used for comparison (to view changes or to create the script). You can also Restore the file from this backup (the Restore button), if you change your mind before checking it in.

Checking files in. All the new, deleted or checked-out files are visible in the check-in area. By double clicking on a file there, you may review the changes you've made to it. You'll see a two-pane display. The left pane is actually an editor. The right pane highlights the differences between the original version of the file and the current version.

Once you are sure that you have completed a certain task, you check-in all the files involved in this task. Code Co-op is a task-based version control system. It operates in units of logical changes to the project, rather than in units of file changes.

The idea behind a task-oriented version control system, like Code Co-op, is that you make all necessary changes to transform your project from one consistent state to another. When you check in your changes, they are supposed to produce a single atomic update to the project. It is highly advisable that this update lead to a project that compiles and runs.
The check-in is done using the Check-in button or through the Check-in item in the Selection menu. In most cases, however, you'll be using the Check-in All button or Check-in in the All menu to check in the whole set of files visible in the check-in area at once. The keyboard shortcut for this action is Ctrl+I. When you check files in, you are prompted for a comment. This comment should describe the task in a sentence or two (it will also serve as a file name for the script—we are not afraid of long file names). You may even use multi-line comments.

Working with Scripts

Differential script. The check-in produces a script. It contains the information about your change—enough to be able to recreate the new state of the project given the previous state.

Distributing scripts through e-mail. The script is a regular file with the extension .snc. It ends up in your Outbox folder. Look for this folder under your project tree. There is a directory called "Co-op" which contains both the outbox and the inbox subdirectories. You should pick up the synch file from the outbox folder and pass it to all the other members of the project. The simplest way is to e-mail the file as a binary attachment. But you can also send it on a diskette or some other way. A diskette is especially useful when you join the project from your laptop. You can easily pass the scripts between your main machine and the laptop using diskettes.

The person who obtains the script, through whatever means, should deposit it in the Inbox folder, also in the "Co-op" directory. Code Co-op will detect the new script and display it in its Mailbox. Notice also that Code Co-op creates a lot of acknowledgment scripts. These too have to be sent to the appropriate parties. Some scripts have the words To all in their names. These have to be broadcast. Others have the name of a particular recipient. These have to be sent to this recipient only.

It makes a lot of sense to create shortcuts to the Inbox and the Outbox folders on your desktop. What we usually do is to open the Outbox using the desktop shortcut and drag all the new scripts directly to a WinZip archive. The recipient of a zipped script will unpack it from the e-mail directly to the Inbox folder of the project. You may also create Old subdirectories inside the Outbox and the Inbox and move the scripts that have already been sent or accepted there. This way you'll avoid the overcrowding of your mailbox.

Synchronizing with a script. The Mailbox area shows all the scripts that are in the Inbox and in the Outbox. The mailbox is intelligent enough to recognize which scripts should be read next. These scripts are marked using the "unpack" icon. Sometimes you'll see scripts marked missing or rejected. If you have a missing script, you have to wait until you actually get it in your e-mail, or ask the person who created it to send it again to you. You unpack scripts using the Synchronize button (it is only active when there is something to unpack) or using the Synch item in the Selection menu (although you don't need to select a script in order to unpack it). The keyboard shortcut is Ctrl-U. This process recreates all the files proposed by the script in your Synch Area and copies them to the project. You may now look at the changes, try to compile and test them, or you can make your own adjustments by checking the affected files out and editing them. If merging has to be done, this is the time to do it.
Review the changes. Once the script is unpacked, you may view the changes by double-clicking on any of the files in the Synch Area. What you see is the comparison of the proposed file against the reference file (in most cases, reference file is either your current project file, or its backup versions from before you checked it out). It is a little more complicated when you have a conflict.
Fig. The view of the changes. Press F4 to go to the next change, or Shift-F4 for the previous change. You can copy a selection to the Windows clipboard by pressing Ctrl-C. The left pane shows the resulting file.

We usually use this opportunity to make a code review of proposed changes.
Accepting a synch. Once you've reviewed the changes, you can accept the synchronization. While in the Synch Area, click on the Accept Synch or Accept Synch All button (or use Accept Synch in the Selection or All menu). What the synch does is to accept (commit) the changes that you've seen in the synch area.
As long as the synch is not accepted, you have the option of "arguing with the synch." You may edit the files that are undergoing a merge or check out files and reject some of the changes brought in by the synch.
If a file is checked out, accepting the synch in fact rejects it.
The keyboard shortcut for Synch All is Ctrl-S.
Merging changes. A merge has to be done whenever two developers make changes to the same file (including deleting it). Code Co-op makes merging changes simple and easy.
Suppose that you have a file checked out and you make some changes to it. In the meanwhile you receive a script that contains changes to the same file you've been editing. When you unpack this script, Code Co-op will detect the possibility of a conflict and will automatically merge the changes. If, as in most cases, the changes don't overlap, it does a pretty good job of merging them. Your edits (including insertions and deletions) as well as the other user's edits will be incorporated in the resulting merged file. When changes do overlap, co-op will try to figure something out.
Whatever the case may be, you have the final say. And this is where Code Co-op really shines. Just open the file in the Synch Area or in the Check-in Area (e.g., double-click on it). Below is an example of what you might see.

Fig. File merge display.
The right (diff) pane shows, in various shades of yellow and green, the edits done by you up to the point when you unpacked the synch script. It also shows, in shades of purple, the edits proposed by the synch.
The left (edit) pane displays the results of the merge. It also serves as a limited-purpose editor (it doesn't support searching and replacing or syntax-sensitive highlighting). It lets you insert and delete text, as well as cut and paste--just like a regular editor. This is where you may modify the results of automatic merge. You may delete lines inserted by the synch. You may copy lines (including the deleted ones) from the right pane and paste them in the left pane. You may do all kinds of arbitrary edits. Notice that the changes that you make in the edit pane will never show in the diff pane. They will, however, remain highlighted in the left pane. You don't have to do all the edits in one sitting. You may, at any point in time, save your changes and exit. You may continue editing the file outside of Code Co-op. If you decide to re-open the file in the synch (or check-in) area at a later time, you will still see all the post-synch changes highlighted in the edit pane and the original merge in the right pane. Finally, when you accept the synch, you'll be left with a checked-out file that will contain all the changes accepted or inflicted by you. You may continue your editing, or you may check the file back in and propagate your changes.
If you chose to discard your changes (in particular, if you haven't made any changes), do the following. Go to the check-in area, select the file in question and click on the Restore button. You will discard your changes and accept the synch changes.
Rejected script. In a distributed version control system it is possible that two scripts miss each other on the way between two developers. The Code Co-op deals with such situation by making one script win and the other lose. When the script that was sent to you loses, you'll see it in your mailbox marked as Rejected. That means, you're fine. Keep on working. The person who sent this script to you will have to resolve the conflict.
Resolving a conflict. You learn that your script was rejected when you unpack the script that overrode it. During the unpacking of such a script, all the changes that you've made in your unfortunate script will be undone. But don't worry. It will be very easy do redo them and re-send the script.
First of all, the files that you've changed in the rejected script will be automatically checked out for you. They'll still have all your changes. If these files are distinct from the files that the synch script wanted to change, i.e., the two sets don't overlap, you're fine. Just accept the synch and then check in the files that were checked out for you. A new script will be generated, proposing the same old changes. Hopefully this time it will not be rejected (if it is, just keep repeating the same conflict resolution procedure). If, however, there is an overlap in files, you'll have to perform a regular merge.

In order to avoid conflicts, it's a good idea to always check your e-mail for incoming scripts before you do a check-in.

What do you think of our product? Would you recommend it to other programmers? Send us feedback. We'll read it!