Source Control and Visual DataFlex 101: The Basics
by
, 17-May-2011 at 06:40 PM (22648 Views)
In The Case for Source Control, I told you why you should use source control. Now I will show you how to use source control with Visual DataFlex. This post will demonstrate the basics of source control from a single developer perspective. Source Control and Visual DataFlex 102: Multi-Developer Use moves on to using source control when multiple developers work on the same project. The purpose of this post is to allow you to start using source control in a fast and efficient manner. See Configuring Source Control for Visual DataFlex for how to configure source control and related tools and what files and folders to check in.
This post is not intended to explain every term or every possible use and technique of source control. There is lots of information on the web and there are many books available on this subject.
At Data Access North America, we use SourceGear Vault as our source control tool. I will demonstrate the techniques we (or in some cases, I) use for Visual DataFlex and Vault. Most or all of these techniques can be applied to the source control software of your choice. The Case for Source Control discusses source control software choices. I will demonstrate this using a local copy of Vault installed on my PC for (free) personal use and the Visual DataFlex 16.1 Order Entry sample workspace. Feel free to use any other version of Visual DataFlex and any other workspace to try what I show here.
Creating a Repository Folder for Your Workspace
Start and log into the Vault Client (I'll just call it Vault from now on) and select the 'source control blog' repository (see Configuring Source Control for Visual DataFlex for how to create this). It should be empty, so you'll just see a root folder with a dollar sign ($) in the folder tree. Right-click on the $ folder and select Create Folder... from the context menu. Name the folder 'VDF 16.1 Examples' and Click Ok.
You'll notice that the folder was not automatically created in the tree, but instead appeared in the 'Pending Change Set' tab at the bottom of Vault. This is where all changes you make will show up. Even if you close and reopen Vault, your pending changes will remain listed in this panel until you either commit them or remove (undo) them.
Since there's just one change listed, click on the Commit All button. The Commit dialog will list the change you are committing and ask you to add a comment. Type 'Create Initial Samples Folder' and click Ok. A plus sign (+) will appear next to the $ root folder. If you expand it, you will see your workspace folder listed.
Right click on the empty VDF 16.1 Examples folder and select Set Working Folder... from the context menu. I will select 'C:\Visual DataFlex 16.1 Examples' (or wherever your VDF 16.1 samples are installed). Check the 'Force all subfolders to use inherited working folder' checkbox and click Ok.
Now, if you configured your options to 'Show non-version-controlled files ghosted in file list' and 'Show non-version-controlled folders ghosted in folder tree', you will see all subfolders of the samples folder (all the sample workspaces) as they appear on your hard disk.
Checking in a Workspace
Right-click on the VDF 16.1 Examples folder and select Add Files/Folders.... from the context menu. Browse or scroll to 'C:\Visual DataFlex 16.1 Examples\Order Entry'. Click the + sign next to Order Entry.sws workspace to select the workspace folder and all subfolders and files. By default, Vault is smart enough not to select compiled programs, so you will see that .exe files in the Programs subfolder are not checked and the workspace folder and Programs folder check boxes are shadowed to indicate that not all files in them are selected. See Configuring Source Control for Visual DataFlex for details on which files to check into source control.
As before, no changes are actually checked in until you commit them. Click the Commit All button and enter 'Initial Check-In of Order sample'. After the check-in, take some time to browse the checked in folders and files and the information Vault shows you.
Using Labels
Labeling a version of a checked in workspace or project allows you to identify it as a complete set in its current state. Such labels can identify something formal, such as a shipped product version (for example, Visual DataFlex 16.1 as released) or it can simply identify a known state of a project (e.g. "this is a known stable version of Project X before adding feature Y"). Using this feature will allow you to easily "roll back" an entire workspace to a specific known point in the development process. Without labels, you can still "roll back" changes you made to your project, but you may have to do so one or more files at a time.
Right-click on the Order Entry folder in Vault and select Label from the context menu. In the dialog, type 'Installed Version from DAW' as the Label and 'This is the version of Order that ships with VDF 16.1.' as the comment, then click Ok.
Making and Checking In Changes
Now, using Visual DataFlex Studio, open the workspace you just checked in. Leave Vault open. Open Customer.vw in the visual designer and drag its outer border to make it slightly larger, then save the file. Switch back to Vault, and you will notice that it has already detected and listed this change in the Pending Change Set panel.
Back in the Studio, right click on the tab dialog control in the same view and append a tab page to it, then save the file again. Switch back to Vault, and you will notice that it has updated the date and time for the changed file in the Pending Change Set panel.
Right-click on the line listing Customer.vw in the Pending Change Set panel and select Show Differences... from the context menu. In the Show Differences dialog, accept the defaults and click Ok.
The image above shows the file differences in Beyond Compare, with the Repository (checked in) version on the left and Working version (the file on disk that you've been working on in Visual DataFlex Studio) on the right. I've chosen to only show lines that have changed to make the screenshot smaller, but you could easily show the whole files on both sides with the changed lines in red.
Once you have viewed the changes and know that they are good (meaning that they are only the changes you've made and want to commit to source control), close the difference viewer tool, right-click on Customer.vw and select Commit Selected Operations... from the context menu. Enter 'Resized view and added a tab page.' as comment and click Ok to commit the change.
Let's make one more change to the same file just to make it a bit more interesting. Back in the Studio, right click on the tab dialog control in the same view and append one more tab page to it, then save the file again. Commit the change in Vault with the comment 'Added one more tab page.'.
Viewing Revision History
If you click on the AppSrc subfolder in the Vault folder tree, you will see that Customer.vw now lists 3 as the local and remote version. This tells you that 2 new versions of this file have been checked in since the original (version 1). Right click on Customer.vw and select Show History... from the context menu. In the History Query Filter/Sort dialog, leave all the defaults and click on Ok. This brings up the History Explorer:
You should see a history list very similar to mine (ignore the second line from the bottom in my listing, it's only there because I was working with interim version of VDF 16.1 while writing this post) which shows you all of the changes you checked in for Customer.vw, including a comment showing what change was committed.
Here, you can also select any two versions of the file listed, right-click and select Diff... to see the differences between those two file versions. For example, when viewing the Diff between versions 2 and 3, you will see the last tab page added to this file.
Rolling Back Changes
So let's assume you've made some changes that didn't work out and want to undo them. In our case, let's get rid of that last tab page we added to the view, it turns out we didn't need it. In the History Explorer, select Version 2 of Customer.vw, right click and select Rollback from the context menu. This places a Rollback entry in the Pending Change Set panel.
Right-click on the entry to commit the rollback operation. Enter 'Roll back to version 2, we didn't need the extra tab.' as the comment and click Ok. The version of the file in the repository is now reverted to the previous version.
Updating Working Files
Note that the status column now shows 'Old' and the local and remote versions do not match. This is because only the repository version of the file was rolled back, but the live working version of the file on disk in your workspace still contains the change (plus any other changes you could have made since then).
We need to update the working version of the file with the change (the rollback) we made in the repository. To do so, right click on Customer.vw in the file list and select Get Latest Version... from the context menu. In the Get Latest Version dialog, choose to overwrite the modified local file, since we don't care about any other changes made to the working file version. Select make all files writable and click Ok.
Now the status column is cleared and the local and remote versions match, meaning that there is no difference between the current file version in the repository and the working version on disk. If you view the history for Customer.vw now, you will see all the changes you have made, including the rollback, with a nice set of comments explaining why each change was made.
I hope this shows what even developers working on solo projects can get out of source control. While source control is a big topic, you can jump in relatively easily. As with any new tool, you will make mistakes and learn and improve over time, but it's quite simple to get started.
Tips
If you rename files, use the source control tool's rename function. If instead, you delete a file from the repository and check in a renamed version, you will lose your change history and with it one of the main reasons to use source control in the first place.