Upgrading SVN approach

Subversion (also known as SVN) is a popular software versioning and revision control system software (see http://en.wikipedia.org/wiki/Apache_Subversion). In the following example, we will use SVN to upgrade an existing user-customized Geoportal Server implementation with a newer Geoportal Server release.

Prerequisite:

This example uses TortoiseSVN (http://tortoisesvn.tigris.org/) as the SVN client for Windows.

Note on Versioning: There are several approaches to organizing a version control system and there are active debates on the web about different methodologies. The following example takes a very basic approach. It assumes that geoportal server is not yet managed within a version control system. The main focus is on using the SVN tools for merging a new geoportal release into a user's existing configured geoportal. We advise geoportal implementers to consider what version control methodology is most appropriate for their project and use the following example as guidelines that can be adapted to a specific project.

Procedure:

Step 1. Add your currently configured, possibly customized, Geoportal Server deployment to SVN.

• Go to folder where you have currently deployed geoportal server

Example: /webapps/geoportal Recommended additional step: Copy the geoportal.xml file from the /conf/Catalina/localhost folder to /webapps/geoportal/META-INF folder. Rename the geoportal.xml file to context.xml. (Why do this? First, it saves your JDBC connection information. Secondly, if you repackage your geoportal installation as a war file and include a context.xml file in the META-INF folder, the geoportal.xml file will automatically get created from the context.xml file when you redeploy the .war file)

• Right-click on your geoportal folder (in the Tomcat webapps directory) and run the TortoiseSVN Repo-Browser:
• Create a folder in your SVN repository for your geoportal configuration. Use the Right-click > 'Create Folder' command to create a 'myGeoportal/geoportal' folder in your repository:
• Right-click on the 'myGeoportal' folder, select the 'Add Folder' command and select the geoportal folder from your Tomcat\webapps directory
• When the 'Add folder' process is complete, you should see the following in your TortoiseSVN Repository Browser:

Step 2. Download a new Geoportal Server release and unpack it.

• Download a new Geoportal Server release from https://sourceforge.net/projects/geoportal/files/ to a working directory.

Example: C:\geoportalServer\newRelease

• Unzip the release and locate the geoportal.war file
• Make a copy of geoportal.war and rename it as geoportal.zip
• Unzip geoportal.zip
• You should now have a folder called 'geoportal' in the C:\geoportalServer\newRelease directory containing the following folders:
  • Catalog
  • Csw
  • META-INF
  • Misc
  • Webhelp
  • WEB-INF
  • Widgets

Step 3. Check out the user-configured Geoportal from your SVN repository

• Create a folder where we will begin the merge.

Example: C:\geoportalServer\myGeoportalMerge\geoportal

• Right-click on the myGeoportalMerge folder and use the TortoiseSVN > SVN Checkout command. Select 'myGeoportal\geoportal' from as the item to check out from SVN.
• Refresh the Windows Explorer view (F5 key) and you should see that TortoiseSVN has tagged the geoportal folder and its contents with green check, indicating that all the folders and files checked out from SVN are current and in-sync with the SVN repository version.

Step 4. Combine the new Geoportal release with the user-configured Geoportal

• Copy the geoportal folder from the C:\geoportalServer\newRelease\ to C:\geoportalServer\myGeoportalMerge. Confirm ('Yes to all') for over-writing and replacing all existing files with the contents coming from the new Geoportal release.

Step 5. Inspect the merged file changes and reconcile differences

• Refresh the windows explorer view of the geoportal folder in C:\geoportalServer\newRelease. Notice that some of the folder and file icons have changed from a green check to a red exclamation point!
• Folders with a red exclamation indicate that some of the file contents have changed from the version that was checked out from the SVN repository.
• At this point, you need to inspect all the folders and files with red exclamations and make a note if the folder (specifically its file contents) contained user-configured changes or customizations. At a minimum, the user-configured geoportal (myGeoportal) will contain deployment-specific changes to gpt.xml in the WEB-INF\classes\gpt\config folder.
• If a folder is flagged as a change, but you know the myGeoportal deployment did not contain any user changes, then you know that the changes are due to the newRelease geoportal. In this case, right-click on the folder and select SVN Commit. You will then be shown a dialog that allows you to select All or Some of the files that you want to commit to the SVN Repository. Afterwards, TortoiseSVN will change the folder icon to a green check mark.
• If a folder is flagged as a change, AND you know the myGeoportal deployment also contained user changes, then you know that the changes need to be reconciled between the newRelease geoportal and the previous myGeoportal geoportal version. In this case, select the file that needs to be reconciled, right-click on the file and select Tortoise SVN > Diff

Example with WEB-INF\classes\gpt\config\gpt.xml: The TortoiseMerge application will start up and display the original file (from the SVN Repository) and the working copy, highlighting text areas that are new, deleted, or changed. There are several methods and tools in TortoiseMerge that one can use to reconcile differences. The most basic one is to right-click on the line that you want to transfer to the Working Copy version and select 'Use this text block'. When you have completed all line by line changes, click Save file in TortoiseMerge and then select Refresh (Ctrl-R). This will re-compare the files. Do one more inspection (line by line) and to make sure all changes are correct. Quit TortoiseMerge when satisfied.

Step 6. Perform final commit to the SVN Repository. At this point, you should have reconciled all user-configurations and customizations that you want to bring from your previous (myGeoportal) geoportal configuration.

• Now, right-click the geoportal folder in the myGeoportalMerge working directory and select 'SVN Commit'.
• Expect to see an dialog alert with the message 'No files were changed or added since the last commit. There's nothing for TortoiseSVN to do here Do you want to see the unversioned files?' Select 'Yes'.
• In the next dialog, select all the unversioned files (the 'Select/deslect all' choice under 'Show unversioned files'. These files represent fodlers and files that were added to the new geoportal release that were not present in the previous myGeoportal version.
• Add a comment about this commit and click 'Ok'.

At this point, you have a new merged Geoportal in SVN.

Step 7. Optional: Check out your new merged geoportal.

• Navigate to \webapps folder.
• Right-click on the geoportal folder and select SVN Checkout
• Click OK to the following dialog
• You should now see a versioned copy of geoportal in your webapps, indicated by a green check on the folder icon.

Restart Tomcat and make sure your new geoportal is working correctly. If not, you may use SVN to revert geoportal to a previous from the SVN repository.