Best Practices?/Getting Started?

[BobWalsh]

Based on Mike Gunderloy's new book, Coder to Developer, I've decided to adopt Vault. I swore off source control years ago when VSS ate 3 months of hard work.

That said, I'm looking for real top level Best Practices, geared to experienced programmer whose relatively inexperienced with source control mumbo jumbo (after VB6, VB NET, ASP NET, HTML, XML et. al, whatever I knew about VSS is gone.)

* Bullet Points/Checklists Work!

I'll be happy to package any replies to this post as a single doc for the good of all.

Regards,
Bob Walsh

[BobWalsh]

Here's one I learned this morning:


If Vault fails to show in VB6 IDE, check the
the vbaddin.ini file. it should have a entry vbscc= 1. file is in \Windows.

[jeremy_sg]

Bob,

First off, browse around the Knowledge Base at http://support.sourcegear.com/viewforum.php?f=13. We've tried to keep these articles updated to handle all of the issues that people run in to. The very first KB article that I want to make sure that you read is choosing between the IDE and GUI client, which is located at http://support.sourcegear.com/viewtopic.php?t=195. The summary is that you will probably be happier in the long run if you use the GUI client instead of the IDE client. There are lots of limitations in the IDE that are related to the fact that Vault has almost no control over the user interface. The GUI client is a much more consistent and less frustrating experience. If it sounds like I'm trying to scare you away from the IDE client, that's because I am.

The rest of this reply is assuming that you're using the GUI client.

Step 1. Add things to source control. You can do this using the VSS Import or the Add Files dialog. Note that in the Add Files dialog you can click a folder and hit the Add button to add all of that folder's contents recursively. If you want to make sure that no bin or obj directories show up in your repository (it's usually bad form to check in build outputs), then delete them from the folder before you add them, or delete the from Vault after you add them.

Step 2. Set a working folder. Vault needs to have a fresh working folder, because it needs to know the status of all of the files. After this step, all of the files will have status Missing. See http://support.sourcegear.com/viewtopic.php?t=131 for more on file statuses.

Step 3. Get the latest version from Vault. After this, all of the files should have status blank.

Step 4(optional). Check out a file to change. This is optional, because Vault supports CVS style development, where you can modify a file without checking it out. Any files that are checked out or modified go into your pending change set. This tab allows you to see all of the changes that need to be checked in.

Step 5. Edit the file, however you want.

Step 6. Review all of the changes that you made in the pending change set. You can use Show Differences from the context menu to look at the exact change that will be checked in.

Step 7(optional). If someone else has changed the file while you were working on it, you can use the Get Latest operation with Attempt Automatic Merge to put those changes into your working file. Vault will not let you check in a file if you haven't merged the changes. For more on Get Latest, see http://support.sourcegear.com/viewtopic.php?t=162.

Step 8. Check in your changes. You can select multiple items in the Commit dialog to make sure that all of your changes make it in at once.

That's just the basic way of working with Vault.

[BobWalsh]

Hi Jermey

Thanks for your lengthy post. It answers a lot of questions, but not all.

Let me boil your reply down, add a few things I think are true, and get your confirmation that I have this right with VB6.

1. Use the client app, not the IDE addin. It's better.
2. Create a folder for each project you want to adminster with Vault.
3. Create a folder within each of those folders, called trunk. This will be the state of your project as of now.
4. Set up folders in trunck for your code, docs, tests but not your executables/dlls [why? - seems like you want to keep the actual working version too]. Add your files to these folders using Add Files. You can add entire folders by selecting them and clicking Add. [Why the totally non-standard folder tree in this dialog?]
5. Set each Project's working folder. This is the folder on your PC that files will be checked out from Vault to and checked into Vault from.
6. Consider what checkin and checkout options you want to have. First, do you want to use the traditional checkout-edit-checkin approach or the more powerful more edit-merge-commit style of source control.

There are two primary patterns for working with a version control tool. One way is to checkout each file before editing, often with an exclusive lock that prevents others from editing the file. When you're done with the file, you check it back in, releasing it for use by others. We call this the "checkout-edit-checkin" style of development. Most SourceSafe users work this way.

Another approach is often called the "edit-merge-commit" style of development. In this style, files in your working folders are usually left in a writable state when you retrieve them. When you want to edit a file, you simply do so. The version control tool will automatically notice that you have made changes. Your changes are submitted to the repository when you "commit" them. However, you may not commit your changes if anyone else has modified this file since the last time you retrieved a baseline from the repository. In this case, you must retrieve the latest changes and merge them into your working copy of the file. After doing so, you may proceed to commit your edited version of the file. The source control tool facilitates this process by helping keep track of the versions and making the merge simple.

Users tend to have extremely strong and divergent opinions about which style is better. Many users do not trust the "edit-merge-commit", preferring the safety of knowing that a given file may never be modified by more than one person at a time. In contrast, those who have used the "edit-merge-commit" cannot imagine returning to the more tedious "checkout-edit-checkin" approach.

Vault was designed to allow each user to make this choice individually. The default behavior is "checkout-edit-checkin", which will be most familiar to SourceSafe users. But those who prefer "edit-merge-commit" are free to configure their client accordingly. We informally refer to this configuration as "CVS mode", since the "edit-merge-commit" style of concurrent development was made popular by CVS.

You can set whether to use CVS or not by going to Option Pane [where is it?]

7. Depending on your choice in #6 above, there's a range of options you want to explore [yeah, and I have as yet found anything that gives me a why to do these options as opposed to the how of doing them.]

8. If you are using CVS, resume your developing then merge and commit your new code (and documents) on a daily basis. If you are using checkin-edit-checkout, use the Vault client to checkout the portions of the code you plan to work on, then use the Vault client to check them back in.

9. Besides protecting your code, Vault makes it easy to make explore potential changes or to propegate code fixes in earlier versions of an project forward. See XXXX for more information on Branches. [And no, the single paragraph "Example" in the help file is not sufficent. You NEED a page on your site with SCREENSHOTS that walks through when/how/why to use Branches.]

Let me know what you think jeremy.