Checking files out for edit

Of course, the reason files are stored in Razor is to provide a controlled mechanism for access and modification. Developers obtain writable copies of the files by selecting the ones of interest from the main display of the versions program and selecting the Checkout for Edit button. Doing so will bring up the following panel.




The user must first decide where the writable copy of the file is to be placed. The directory name can be typed directly into the Check-out to field, or the cd button can be used. Using the latter method brings up its own panel which allows the user to `walk' to the desired destination by mouse interaction with scrolling lists (reminiscent of the methods discussed for introducing files).

For files being checked out that are included in one or more folders in the Razor database, they will be placed into the Check-out to location including the appropriate subdirectories. When the Path is absolute check box is selected, files will be placed directly into the Check-out to destination.

The Clear button can be used to clear the title and description entries. Cancel cancels the check out action and returns to the main display. Help is, well, help.

Filling in comments

There are two mechanisms for associating user comments with the check-out.

After specifying where the files should be placed, the user must enter a brief reason why he is checking the files out. This Title field must be filled in with something for the check-out request to be processed.

Separately, the user has the option of entering a longer, more thorough set of comments in the Description field. These notes may be of whatever length and purpose deemed necessary. They will be stored in the Razor database, and can be recalled later as necessary to gain insight as to not only which files the user checked out, but what the thinking was at the time.

NOTE: Many version control systems allow comments only when the file is being checked back in. Razor allows comments to be made both before and after changes are made to the files. The notes made during check-out of files can address what the developer is hoping to accomplish. These notes are shown during the check-in process, and may be modified to reflect what actually got done.

Associating issues to editing activity

In addition to the above means of commenting on a check-out effort, users may directly relate the activity to one or more issues in the problem tracking system. In many ways, this makes more sense than making comments directly on the check-in or check-out panels themselves.¹

This is very powerful. It allows you to use the problem tracking system as the heart of your development process, allowing you to directly associate what you are doing against the stated reason of why you're doing it. This can come back and help later as you pull together threads which define your product releases!²

In order to do this type of association, you of course need to have both the issues and versions tools running at the same time on your display against the same database. Given that, the first step is to identify the relevant issues from the problem tracking system. Once done, there are two different ways to perform the association.

The drag-and-drop method³

Once one or more issues are selected on the main display of the issues program, a small icon will appear to the right of the toolbar, just below the menu on the main display. Grabbing this icon with either the Select or Extend mouse button allows you to drag it over to the small scrolling list on the check-in/check-out panel. This icon only appears if you are using Razor's version control tool and have groups defined in the database. Of course, if you never create a versions control group, then you will never see this icon




You can repeat this maneuver as many times as necessary.

The copy-and-paste method

After selecting one or more issues from the main display of the issues program, the user may use the menu button of the mouse to bring up a small list of options. Choosing Copy Issues will push the list onto an internal clipboard area for later use.




After the issues have been selected, the user then returns to the versions program and brings the cursor over the small issues scroll area on the panel. Again, by using the menu button on the mouse, a short list of options will appear. Selecting Paste Issues will drop the issue numbers into the scrolling list.




This Copy-Paste effort can be done as many times as necessary to get an accurate list. The menu associated with the small issues list also allows the user to select and deselect all members of the list as well as delete members from the list if necessary.

TIP: If the issues program is running on your display against the same database (which it probably is), you can double click on any of the issue numbers in the scrolling list to view a copy of the full issue for review and possible modification.

The steps outlined here for associating issues to a check-out activity are the same as those that can be used wherever version control commentary is allowed. This includes checking a file back in, introducing new files to the database, etc.

¹ Razor's "out-of-the-box" stance is to make this type of association optional; at the sole discretion of the user. It is possible however to force users to make the association, based on local rules. An example of how this would be done is offered on page 241.
² See "Defining threads by related issues" on page 131.
³ This feature is not available in the PC Client.