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 version 8.

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 (except for the overall relocation of files into the CMS sub-folder that occurs during the version 8 upgrade).

  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. Create a folder named CMS in the root of the checked out project.
  6. Move all of the project's folders and files into the CMS sub-folder (make sure the move operation retains source control history).
  7. Check in (commit) the move operation.
  8. Check out the CMS folder and its entire content again.
  9. Remove files that are no longer present in Kentico 8 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
      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
      git rm CMS/CMSModules/AdminControls/Controls/UIControls/PreviewEdit.ascx
      
  10. 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.



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

  12. Add all new files to the source control (based on the list created in step 10). 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
    tf.exe add "c:\Kentico\CMS\App_Code\CMSModules\Ecommerce\Extenders\CustomerEditExtender.cs"
    
    Git - Command for adding a new file
    git add CMS/App_Code/CMSModules/Ecommerce/Extenders/CustomerEditExtender.cs
    
  13. Check in (commit) the changes to your main source control repository.
  14. 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.