Upgrading projects under source control

If you use a source control system (such as for example Team Foundation Server or Git) to manage the files of your Kentico web project, you may need to perform additional manual steps when upgrading to a newer version.

The following process allows you to retain most of the source control history and annotation data for files when upgrading:

Limitation: Currently, you cannot easily preserve source control history for files that the upgrade renames or moves to a different location.

1. Back up your Kentico web project files, database and the related source control data.

2. Create a separate copy of your web project and database (outside the scope of your source control system).

3. Perform the standard upgrade for the copy of your project, including all required steps (project file and database upgrade, steps before and after the upgrade, handling of customizations).

4. Check out all files of the original project in your source control environment.

   Note: Before you perform the checkout, make sure that no files are locked or have pending changes.

5. Remove files that are no longer present in the target Kentico version from your source control repository:

   1. Open upgrade.xml in the upgrade installation directory, which contains a list of files that the upgrade deletes.

   2. Delete the listed files from your checked out web project. You can prepare a command line script that automates the process, for example:

      Team Foundation Server - Commands for handling a file deleted by the upgrade

      Copy

      
      
      
       tf.exe undo "c:\Kentico\CMS\CMSModules\AdminControls\Controls\UIControls\PreviewEdit.ascx"
       tf.exe delete "c:\Kentico\CMS\CMSModules\AdminControls\Controls\UIControls\PreviewEdit.ascx"
      
      
       

      Git - Command for deleting a file removed by the upgrade

      Copy

      
      
      
       git rm CMS/CMSModules/AdminControls/Controls/UIControls/PreviewEdit.ascx
      
      
      
       

6. Perform a comparison (difference operation) between the upgraded copy of the project files and the checked out original version. The output of the comparison must be a list of new files that were added by the upgrade.

   You can use either the functionality of your source control system or other comparison tools, such as Beyond Compare.

   Note: The upgraded project may contain files that are not included in your source control, for example site folders containing data files, images, etc. To get the most accurate set of differences, you need to remove or disregard such files.

7. Copy all files from the upgraded project into your checked out source control repository and overwrite all existing files.

8. Add all new files to the source control (based on the list created in step 6). You can prepare a command line script that automatically runs the required source control commands, for example:

   Team Foundation Server - Command for adding a new file

   Copy

   
   
   
    tf.exe add "c:\Kentico\CMS\App_Code\CMSModules\Ecommerce\Extenders\CustomerEditExtender.cs"
   
   
   
    

   Git - Command for adding a new file

   Copy

   
   
   
    git add CMS/App_Code/CMSModules/Ecommerce/Extenders/CustomerEditExtender.cs
   
   
   
    

9. Check in (commit) the changes to your main source control repository.

10. Connect your main project to the upgraded copy of the database.

Your project is now upgraded, with source control history preserved for all files that are shared between the two versions.