Lessons Learned in Version Control Doug Hennig Stonefield Software Inc. Email: [email protected] Corporate Web sites: www.stonefieldquery.com www.stonefieldsoftware.com Personal Web site : www.DougHennig.com Blog: DougHennig.BlogSpot.com Twitter: DougHennig Rick Borup’s sessions at previous Southwest Fox conferences really helped me get started using version control for my application development. Since then, I’ve made a ton of mistakes and learned a lot of lessons the hard way. This document discusses what has evolved into my team’s best practices for version control. It’s intended for those who are familiar with version control but are looking for ideas about how to improve their processes. Lessons Learned in Version Control Introduction Before Rick Borup’s “VFP Version Control with Mercurial” session at Southwest Fox 2011, I’d heard all the arguments for using version control but hadn’t adopted it. My thinking was that I’m the only one working on my projects so I don’t need version control. Rick’s session convinced me I was wrong. I implemented Mercurial shortly after, with tremendous help from Rick’s white paper, and haven’t looked back. I now use version control for more than just application development. For example, the tables Tamar, Rick, and I use to manage speakers, topics, and scheduling for Southwest Fox and Southwest Xbase++ are in version control. I’m not going to try to sell you on using version control. I’m also not going to provide an introduction to version control in general or certain version control tools in particular; I assume you’ve already been using version control or at least have enough familiarity with it to follow along. What this document is about is discussing the processes my team at Stonefield Software use and some of the traps we’ve run into along the way. I don’t claim that these are best practices for everyone; they’re processes that work for us. Feel free to adopt and adapt them as you see fit. The examples discussed in this document use Mercurial but the concepts are almost identical in other distributed version control systems (DVCS) like Git. Getting started I’ve started a new application that both I and my wife Peggy will be working on (she’s not actually a software developer; I just wanted to use her name in my examples). So far, the application just consists of a main PRG that runs a form, which just has a single button so far. The form and its controls are instances of classes in my base class library, which is in a folder outside the project folder structure called Framework. The first step is to put the source for the application into version control (actually, the first step is to install a version control system on both machines, but I assume that’s already done). Right-click the project folder, choose TortoiseHG, and select Create Repository Here (Figure 1). You can just accept the defaults in the dialog that appears and click the Create button. You’ll see a new .hg folder and new .hgignore file created, and the project folder has a green checkmark indicating both that it’s under version control and that there are no changes (in this case, because we haven’t added anything to the repository yet). Copyright 2016, Doug Hennig Page 2 of 24 Lessons Learned in Version Control Figure 1. Creating a repository. Right-click the folder again and choose Hg Commit. Select all files by clicking the checkbox at the top, enter a commit message (it’s traditional to use “Initial commit” for the first one), and click the Commit button (Figure 2). Click the Add button when asked if you want to add selected untracked files. All project files now display a green checkmark. Figure 2. The initial commit for the application. Next we need to clone our local repository to a central one where other developers can access it. For now, we’ll do this on a server but later we’ll use a cloud site. Create a folder on the server, right-click it, choose TortoiseHg, and select Clone (Figure 3). Click the Browse button for Source and select the application folder, then click Clone. Copyright 2016, Doug Hennig Page 3 of 24 Lessons Learned in Version Control Figure 3. Cloning a repository on the server. Finally, to create a copy on Peggy’s machine, repeat the steps to clone the repository on the server but use the server repository as the source. Let’s see if everything worked. Open the MyApp project on Peggy’s machine. Oops, we’re getting a warning that SFCtrls.vcx can’t be found. That makes sense: the repository only contains files from the MyApplication folder, not from Framework, so when we cloned the repository on the server and on Peggy’s machine, the files in Framework weren’t included. That brings up the first topic: how we deal with common components. Handling common components Rarely do you start an application completely from scratch. Typically, you use a framework of some type, whether it’s a commercial product such as Visual FoxExpress or Visual MaxFrame or a home-grown version like I use. You probably use other components too, again either commercial products, such as West Wind Client Tools or Stonefield Database Toolkit, or open source, such as VFPX projects or FoxyPreviewer. Usually, rather than having separate copies of these components for every application, developers install these components in directories on their machines and then reference the components from those folders in their projects. That’s what I did with MainForm.scx: it’s a subclass of SFFormTLF in SFCtrls.vcx, located not in the project folder hierarchy but in a folder called Framework that’s referenced by all projects. The problem with that approach is it prevents you from including those common components used by a project in the project’s repository: all the files in a repository must exist in the repository’s folder hierarchy. There are a few solutions to this: Copyright 2016, Doug Hennig Page 4 of 24 Lessons Learned in Version Control Install the common components on each machine. Have copies of the component files in each project folder. Have a repository at a level that includes both the project and the common components folders. Have separate repositories for your project and common components. Let’s look at each of these options in more detail. Install common components on each machine For common components that weren’t created in-house (commercial or open source), you could argue that you don’t need to include those files in any repository. Instead, just install them on each developer’s system. Of course, you need to ensure the same relative folder structure is used on each machine or you’ll have issues with components not being found even though they’re installed. The pros of this approach are: It’s straightforward: your team simply has to worry about source code under your control, not that created by other developers. The repository is small since it doesn’t contain anything outside the project-specific files. The cons for this approach are: It doesn’t help with common components that were created in-house. It’s more work setting up a new machine: instead of just cloning a repository, you have to install numerous other components the project depends on. There could be version problems. For example, if one developer upgrades to a new version of a component but the others don’t, the application may not run properly. Everyone has to keep all components in sync with each other. Copies of the component files in each project folder In each project’s folder structure, include one or more folders containing the common components. You could dump them all into a single folder, even the same folder as your project files, but that would be messy and difficult to manage. A better solution is to duplicate the folder structure you normally keep the components in within the project’s folder hierarchy. For example, suppose you have a folder structure like shown in Figure 4. Copyright 2016, Doug Hennig Page 5 of 24 Lessons Learned in Version Control Figure 4. A folder structure with two projects and common components. In that case, your project folder structure would look like Figure 5 (Source is the folder containing the project-specific files). Note that Application 1 and Application 2 are under version control but Common Files is not (although it could be if desired). Figure 5. Copies of common components go in each project’s folder hierarchy. (Of course, rather than having the folder for each component in the root of the project folder, you could have them under a Common Files folder.) Copyright 2016, Doug Hennig Page 6 of 24 Lessons Learned in Version Control The project-specific code references the copies of the common components from within the project hierarchy rather than from the main Common Files folders and those files are included in the repository for each project. The pros for this approach are: Each project stands alone with no references to anything outside the project’s folder hierarchy. Cloning the repository is easy since it’s self-contained. Setting up a new project is easy: simply copy the folders within Common Files the project uses into the same named subdirectories of the project folder. The project is insulated from changes to common components that may break the application. For example, maybe an update to a West Wind component means changing code that calls the component.