Working with a Version Control System

Size: px
Start display at page:

Download "Working with a Version Control System"

Transcription

1 Working with a Version Control System Summary Tutorial TU0114 (v2.4) March 18, 2008 This tutorial looks at how you can use Altium Designer s built-in version control capabilities to check project files in to and out of your company s version control repository. Background One of the greatest strengths of an electronic authoring and editing environment is the ease with which you can create and modify a file. This capability means that ideas can be captured, explored and matured quickly be it code, user documentation, an image, or your next presentation. It also means that it can be very difficult to keep track of changes made to your valuable files. This need to keep track of changes made to a file, combined with the need for a systematic solution for managing source captured in an electronic form, has given rise to Version Control Systems. Version control systems are software tools that are not only able to maintain a history of the various versions of a file, they also support opening any revision of that file, as well as for ASCII files, comparing changes made between any two versions of the file. Version Control Systems can be operated completely independently of the authoring and editing environment used to create a file. They have an interface that allows you to check files into their central storage area called the repository, a check-out feature to copy a file from the repository to a working folder, an update feature to check back in any changes, and a method of logging information about a change. Typically a version control system will also handle the situation where a file has been checked-out and modified by multiple people, who could then check their changes in on top of each other, potentially losing someone s work from the latest revision. Dealing with this requires tools to compare versions of the file to detect differences, and an interactive tool to merge the differences back into a single version of the file. Before looking at an overview of how a version control system works, it is important to understand the terminology used with version control systems. Even though there are numerous systems available, they generally all use similar terms to describe their functionality. Terminology Check-in To save your working copy of the file into the repository. Referred to as Commit in some version control systems. Check-out To take a copy of a file from the repository into your working folder (sandbox). Typically you will be checking-out the latest revision, but you can also access all earlier revisions. Depending on the VCS the file can be flagged as simply checked-out, or checked-out exclusively (locked). Commit To save your working copy of the file into the repository. Referred to as Check-in in some version control systems. Conflict The situation when two people try to commit changes that affect the same region of the same file. These must be resolved, either using a Merge tool, or manually. CVS Concurrent Versions System, an open source version control system. Altium Designer has a direct CVS interface, allowing you to track and access revisions directly from its Storage Manager panel, making it very easy to compare different revisions of schematic and PCB files. Database The master storage of all the files under version (or source) control, also known as the repository. Log message A comment about changes made to a revision when you check it in. The log messages can be used as a summary of the progress of changes in a file. TU0114 (v2.4) March 18,

2 Project Repository Revision Sandbox SCC SVN Update VCS Version Most version control systems support the concept of a project. A VCS project is a set of related files which can be checked-in/out as a set. The VCS may also support other project-type features, such as setting a version number on all files in a project. The master storage of all the files under version (or source) control, also known as the database. A committed change in the history of a file or set of files. This is the numerical reference supplied by the VCS to track the different editions it is holding of the file. Folder where you check files out to work on them, also referred to as the Working Folder. Source Code Control, a software interface standard defined by Microsoft that allows an editing application to interface to a version control system. Supports actions such as launching the VCS, checking files out, checking changed files in, logging information about the change and examining the revision history. Subversion, an open source version control system. Altium Designer has a direct SVN interface, allowing you to track and access revisions directly from its Storage Manager panel, making it very easy to compare different revisions of schematic and PCB files. The act of checking for and pulling changes from the copy in the repository into your working copy of the file (the compliment of Commit, or Check-in). The process of merging in any differences requires a Merge tool, or manual updating. Version Control System, a generic term applied to any tool that is capable of managing file version history and file retrieval. The term version is normally used to refer to the external reference number allocated by a human to the controlled files, or their output (e.g., in the case of source code). Working copy Your copy of the file that you actually make your changes in. Working folder Folder where you check files out to work on them, also referred to as the Sandbox. Version control basics The basic approach to working with a version control system is to update, or check-out, the project files that you want to work on, from the repository, into a working folder. These can then be modified and saved, and when you decide it is appropriate, the updated files can be committed, or checked back, in to the VCS s repository. Check-out and check-in is performed through a version control system interface. The Altium Designer environment supports the Subversion VCS, which means it can perform some of the Subversion tasks. Subversion is a VCS that manages files and directories over time. It does this by managing any collection of files, not just source code, by remembering all changes made to your files and directories. So rather than being project based the Subversion VCS is directory based. 2 TU0114 (v2.4) March 18, 2008

3 Figure 1. Simple diagram of how Altium Designer interfaces to Subversion The key to how a version control system works is that it monitors the status of files that have been checked-out of the central repository. This means that the VCS knows that a file has been checked-out into your working folder, what revision was checked-out, and if it has been modified since it was checked-out. Each VCS uses its own approach to monitoring files, refer to the VCS documentation if you need further information about this. Figure 1 shows the 3 files in the project My.PrjPcb. All the various revisions of each file are shown in the repository, with the latest checked-out copy in the working folder. When the project in the working folder is opened in the Altium Designer environment Altium Designer recognizes that the project files are under version control, with the current version control status of each file being shown in both the Storage Manager and Projects panel. Communicating to the VCS via the Subversion interface, the right-click menu in the Storage Manager panel allows you to a perform standard VCS actions, such as checking in a changed file. When you right-click and select commit the VCS takes a copy of the file from your working folder, increments the revision number (stored internally in the VCS), and stores the copy of the file in its repository, along with a log message that you can enter to describe the changes made to the file. Most VCS systems don t actually store the entire file with every commit, instead they store the differences from the previous version. The different approaches to accessing files under version control There are essentially two different approaches to giving multiple team members access to the same set of files. You can either: Allow multiple check-outs (referred to as the unreserved check-out model) Restrict file access to one person at a time (referred to as the lock-modify-unlock, or the exclusive check-out model) Allowing multiple check-outs is ideal as it allows your different team members to continue working independently, without having to wait for someone else to check a file back in before they can work on it. However, it does require that you have tools and techniques to resolve the inevitable situation where two people have modified the same file. There are excellent Merge tools available for merging changes in ASCII files, but generally there is not a lot of support for merging changes in binary files. Altium Designer provides schematic and PCB comparison (or diff ) capabilities, bringing the confidence in design change management that diff ing offers to the board design process. While Altium Designer can detect differences between two revisions of a schematic or two revisions of a PCB, it currently does not support Merging, so resolving any differences must be done manually. The Altium Designer Version Control Interface Altium Designer supports Subversion (SVN), Concurrent Versions System (CVS) and other version control systems that support the Microsoft standard SCC Interface. The direct support for SVN gives access to many of the commands that SVN offers, TU0114 (v2.4) March 18,

4 including the ability to create a repository, commit/update files, as well as being able to access file revisions from within Altium Designer. This works well with the schematic and PCB comparison features, making it easy to quickly compare and identify differences between two revisions of a schematic or two revisions of a PCB. Enabling version control To work directly with a VCS you must enable the appropriate options in the Preferences dialog (DXP» Preferences). On the Version Control General page select the SCCI Source Code Control Interface if you are using an SCC Interface compliant version control system. Select the CVS Concurrent Versions System option if you are using the Concurrent Versions System version control system. Select the SVN Subversion option if you are using the Subversion version control system. Figure 2. Version Control - General preferences - choosing SVN as the VC provider For Subversion you will need to additionally: Specify the path to the main executable, usually svn.exe. This will then allow Altium Designer to perform most of Subversions repository actions such as commit and update Specify the path to the admin executable, usually svnadmin.exe. This will then allow Altium Designer to create a repository. If you already have a repository you may skip this option. Restart Altium Designer to confirm your choice of version control system Note that it is necessary to have Subversion or later installed in order for the SVN features to work correctly in Altium Designer. Earlier versions such as the Subversion does not work properly in Altium Designer. 4 TU0114 (v2.4) March 18, 2008

5 The Storage Manager panel All VCS-related actions are performed through the Storage Manager panel, you can display it by clicking the System button at the bottom right of the workspace and choosing the Storage Manager entry from the menu that appears. Performing VCS type tasks in the Storage Manager panel is described in detail later in this tutorial. The Projects panel The current VCS status of each file that is under version control is displayed next to the file s name in the Projects panel. The status is dependent on which VCS method you are using, and it can be one of the following: SCCI [blank] Version control disabled file has not been added to the VCS. [blank] Not in version control - file has not been added to the VCS. No modification The file is checked in to the repository, and your local copy is up to date. Depending on the provider, your local copy may be marked read-only so that it cannot be modified until you Check Out. Out of date The file is checked in to the repository, but your local copy is out of date. Use Get Latest Version to update your local copy. Checked out exclusively by me You have checked out the file exclusively, but there are no changes to check in. Use Undo Check Out when you are finished with the file and want to allow other people to check it out. Modified exclusively by me You have checked out the file exclusively and modified it. Use Check In to check your changes into the repository or Undo Check Out to discard them. Locked exclusively Someone else has checked out the file exclusively. You cannot check out the file until he or she selects Undo Check Out. Depending on the provider, your local copy may be marked read-only so that it cannot be modified. Locked exclusively by me You have somehow managed to check out the file exclusively somewhere else (perhaps in another directory). Refer to the documentation for your Source Code Control plug-in on how to remove the lock. CVS and Subversion [blank] Version control disabled file has not been added to the VCS. [blank] Not in version control - file has not been added to the VCS. No modification The file is checked in to the repository, and your local copy is up to date. Depending on the provider, your local copy may be marked read-only so that it cannot be modified until you Check Out. Out of date The file is checked in to the repository, but your local copy is out of date. Use Get Latest Version to update your local copy. Modified the checked out file is locally modified by you. Save the file and check in / commit the file to the repository. Conflict the file has been committed by some one else before you had a chance to commit this file. Missing the file is present in the repository but not in your working folder. Use Restore menu item from the menu by right clicking to obtain a copy from the repository in your working folder. You can right click and select Refresh Status to refresh the current VCS status of each file on the Projects panel. A document that is not in the version control database is represented by no icon. TU0114 (v2.4) March 18,

6 Adding directories and files to the VCS with Subversion Before using version control, the project files must be recognized by both the VCS and Altium Designer as being under version control. This process can be different for the different VCS methods, so we will demonstrate how to do this with Subversion. Creating a Repository Subversion saves its version control information in a central repository. The repository stores information in a hierarchy of files and directories, referred to as a file tree. If you do not already have a repository you will need to create one. To create a repository: Display the Storage Manager panel Right-click and select Create Repository Specify a directory to contain the Subversion repository in the following dialog. The Repository Type is how Subversion manages the storage of the repository. Adding a directory to the Repository Subversion monitors changes to the files in a specified directory. These changes are saved in the repository. The next step is deciding which directory you would like to monitor with Subversion. 1. Open a free file or project 2. Display the Storage Manager panel. 3. You will see the directory structure of the project/file that you have selected in the Folders section of the Storage Manager panel. Select a directory. Altium Designer will not automatically monitor sub-directories. You will need to specify each directory. 4. Select Link Folder to Repository folder from the right-click menu on the Storage Manager panel. 5. This will open the SVN Link Setup dialog which will allow you to link the directory to the Subversion repository. 6 TU0114 (v2.4) March 18, 2008

7 6. Confirm the Local Directory is the directory you have selected in Step 3 and that the Path To Repository specifies which Subversion repository you want to use. Then click Ok. This directory is now being monitored by Subversion. This is indicated by the chain icon next to the directory name in the Storage Manager Panel in the diagram below. Adding files to the Repository After adding a directory to the Subversion repository, you now need to specify which files in that directory you want to add to the repository. All files in a directory that has just been added to the repository have the status Not in version control. With Subversion you can add files to the repository by: 1. Select a directory which has been added to the repository 2. Select one or more files in the Storage Manager. The option Only Show Files in the current Project controls which files are displayed in the directory. 3. Select Add to Version Control command from the right mouse menu 4. Add a comment to indicate the reason for adding the files, if desired, then click Ok. After you have added the files to the repository, the status of the files are changed to No Modification as indicated in the diagram below. TU0114 (v2.4) March 18,

8 The VCS Revisions section of the Storage Manager panel has a blue arrow that shows the revision of the file that you currently checked out. With this version of Altium Designer, files cannot be locked exclusively when being added to the repository with Subversion. Committing/Updating files in and out the VCS Once the project and its files have been added to the VCS you can check them out when you wish to work on them, and then check them back into the VCS when you have completed the work. Your day-to-day work VCS practices will depend on your company s requirements, and to some extent the approach of the VCS. For example, if your VCS favors the lock-modify-unlock model, such as Microsoft s Visual SourceSafe, then your company policy might be that you should always check your work in at the end of the day so that the file is made available to others. On the other hand if you are using CVS or SVN, which are built around the philosophy of multiple check-outs (the unreserved check-out model), then your company policy might be that you can keep design files checked-out in your working folder, and are only required to check-in at major file update points. Updating a file from the Repository When using the CVS or Subversion VCS systems you use the Update command to check out a working copy of the file from the repository. Then, use the Update command to ensure that your working copy includes any modifications made by other users who are working with the file, before checking your own modifications into the repository using the Commit command. To update a file, select one or more files in the Storage Manager panel and select Update from the right mouse menu. When using an SCC interface-compliant version control system, check-out a file by right-clicking on the file name in the Storage Manager panel and selecting Check Out from the context menu. The VCS keeps track of what is in the repository compared to what exists in your working folder, so when you check-out a file the VCS copies the latest revision of the file from the repository to your working folder (nothing will happen if they are the same revision). Altium Designer supports this further, by disabling the Update command in the Storage Manager when the file in the repository is identical to your working copy. If the file was open in the Altium Designer environment when you executed the Update command you should close and reopen the file in order to display and work on the checked-out version of the file. The update status After updating a file its VCS status is shown in the Storage Manager panel as No Modification. This indicates that the repository and working versions of the file are the same. The figure below shows the status after updating the project files when using CVS or Subversion version control systems. 8 TU0114 (v2.4) March 18, 2008

9 Figure 3 VCS file status for Subversion The figure below shows the check-out status for various project files with SourceSafe as the VCS. Since SourceSafe uses the lock-modify-unlock model then the file can be checked out exclusively, or simply checked out. Figure 4 VCS file status for SourceSafe For the file that is checked out exclusively, another designer will not be able to check-out this file. The VCS will have a mechanism to allow them to get a copy of the file, but the only person that can check-in an updated version of the file is the designer that checked it out exclusively. With this version of Altium Designer, files cannot be locked exclusively when being added to the repository with Subversion. Committing files into the Repository When you have finished working on a file, you need to check it back in to the VCS. This process will copy the file from your working folder back into the repository, incrementing the revision number. Note that if the file you want to commit is active (open), it should be saved prior to committing, or else the last saved version of the file will be checked in to the VCS and not the open file. Right-click on one ore more files you want to commit in the Storage Manager panel and select Commit. If you are using CVS or SVN you will not be allowed to perform a Commit if someone else has committed an update since you checked out your copy of the file. In this case you will be required to perform an Update first. In CVS and SVN language, an Update is the act of applying changes that exist in the repository copy to your working version of the file, once this is done you will be permitted to Commit the file. Since this is not possible with binary files such as schematics and PCBs, the result of an Update will be that CVS/SVN will check-out a copy of the file to your working folder, with a hash (#) character at the start of the filename. Use the difference feature described in the following section to identify any differences and help you decide how the differences should be resolved. Showing differences between files Probably one of the most often used features in a VCS is the comparison, or difference checking tool. Typically the VCS will include an ASCII diff tool, and there are also excellent 3 rd party ASCII diff tools available. Altium Designer provides diff ing for schematic and PCB files. You can use this capability to show changes such as a schematic component being moved, or the path of a route being altered. TU0114 (v2.4) March 18,

10 Figure 5 Use the Difference capabilities to quickly identify changes in your schematic and PCB design files If you are using CVS or SVN as your version control system you can perform a diff directly in the VCS Revisions section of the Storage Manager panel, simply Ctrl+click to select the 2 revisions, then right-click and select Compare from the context menu. Since the SCC software interface does not support passing a list of revisions to Altium Designer, for any other version control system you will need to manually check-out the revisions of the files you want to compare, open them both, and select Show Physical Differences from the Projects menu. Enable the Advanced mode in the Choose Documents to Compare dialog, then select the 2 documents. Once the 2 files have been compared the Differences panel will list all differences between the files, double-click on an entry to examine it. Removing files from the VCS Some VCS systems allow you to remove directories/projects. By removing a directory/project from the VCS, means it will no longer be associated with version control and the link between Altium Designer and the VCS software will be removed. Removing the directory/project alone does not remove all associated project files from your VCS however. They will appear again if the project is added back into the VCS and a refresh is carried out to resynchronize the system (right-click on the project file entry in the Storage Manager panel and choose the Refresh Status command). You will need to use the VCS interface to permanently remove project files from the repository. Removing a file from the VCS To remove the selected files from your VCS: 1. Right-click on one or more files that you want to remove in the Storage Manager panel and select Remove from Version Control. 2. The status for the removed file will change to an empty box [Not in version control] in the Projects panel. Removing a directory from the VCS With this version of Altium Designer, directories cannot be removed from the VCS repository. Refreshing the status Should you wish to make sure the status of your files is up to date, use the Refresh Status command. This command can be used at any time, but is especially useful when you have performed an action, such as checking in or out, directly in the VCS software. 1. Right-click on the project filename in the Files section of the Storage Manager panel and select Refresh Status. 2. The link between the active project in Altium Designer and the project that resides in the VCS is checked and the status of the project and its related files is refreshed. The corresponding status is updated both in the Storage Manager panel and in the right-hand box next to each file's name in the Projects panel providing the Show VCS status option is enabled in the associated options for the panel. Access these options on the System Projects Panel page of the Preferences dialog (DXP» Preferences). 10 TU0114 (v2.4) March 18, 2008

11 You can also use the F5 key on the Storage Manager panel to refresh the VCS status. Showing a file s VCS history You may wish to view the history of a file in your VCS. If you are using the CVS or Subversion version control systems history of the selected file is shown directly in the VCS Revisions section of the Storage Manager panel. To review any revision, select any of the VCS revisions and select Open from the right-mouse menu. This will open the file in Altium Designer. If you are using SCCI version control you can view the history: 1. Right-click on the file whose VCS history you want in the Storage Manager panel and select Show History. 2. Login to the VCS if required. You may get a History Option dialog prior to seeing the history of the file, such as the one shown in Figure 6. This will depend on VCS software you are using. Figure 6 Click OK in the History Options dialog to select the revisions of interest from a list 3. Click OK and the history of the selected file inside the VCS will be shown. The information shown will depend on the version control software you are using. Consult your VCS software documentation for more information on these dialogs. Resources SVN community website SVN online manual CVS community website CVS installation tips CVS manual (known as the Cederqvist, after the author) Using and administering CVS Alternate CVS download site TU0114 (v2.4) March 18,

12 Revision History Date Version No. Revision 9-Dec New product release 5-Feb Enable VCS in System Preferences added. 21-Dec Re-written to cover Storage Manager. 18-Jul Updated for Altium Designer SP4 14-Dec Updated for Altium Designer 6 24-July Updated for Altium Designer 6.8 minor editing and many images updated. F5 key supported for the Storage Manager panel. 18-Mar Updated Pagesize to A4. Software, hardware, documentation and related materials: Copyright 2008 Altium Limited. All rights reserved. You are permitted to print this document provided that (1) the use of such is for personal use only and will not be copied or posted on any network computer or broadcast in any media, and (2) no modifications of the document is made. Unauthorized duplication, in whole or part, of this document by any means, mechanical or electronic, including translation into another language, except for brief excerpts in published reviews, is prohibited without the express written permission of Altium Limited. Unauthorized duplication of this work may also be prohibited by local statute. Violators may be subject to both criminal and civil penalties, including fines and/or imprisonment. Altium, Altium Designer, Board Insight, Design Explorer, DXP, LiveDesign, NanoBoard, NanoTalk, P-CAD, SimCode, Situs, TASKING, and Topological Autorouting and their respective logos are trademarks or registered trademarks of Altium Limited or its subsidiaries. All other registered or unregistered trademarks referenced herein are the property of their respective owners and no trademark rights to the same are claimed. 12 TU0114 (v2.4) March 18, 2008