Page Comparison

...

1. Alter the project files for your environment; e.g. update filters/*.properties, add LDAP or other sources to personDirectoryContext.xml, configure the authentication appropriately for your environment, etc.

Updating to newer version

Updating your code with changes from Apereo

...

Cherry-Pick Commits

...

1. Merge in the changes from Apereo (see related sections)
2. Review the updates made to uportal-war/src/main/data, in particular those made to the quickstart_entitites (which you copied and customized).  Determine which changes you would like to incorporate into your customized entities directory.  Create a plan for updating those entities in your dev, test, and prod databases (see Importing and Exporting data for information on using ant data-import).  See more on that below.
3. If you are using the multi-tenancy capabilities of the portal, review the updates made to uportal-war/src/main/resources/org/jasig/portal/tenants/sampledata and incorporate those you would like into your tenant template data set (typically you copy the sample tenant data to your own institution-specific folder and customize it).  Any existing tenants that were created from the previous data set may need to be updated.  See more on that below.

Updating your data with changes from Apereo

The database entities (in uportal-war/src/main/data) are broken into 3 tiers to theoretically allow for easier customization.  Required entities are to get the portal to run. Default entities are for basic portal functionality.  Quickstart entities are for a particular experience and are meant to be copied and customized for your institution. Some of the quickstart entities override the default entities, providing additional data such as categories and groups that are applicable to the portlets in the quickstart data set. The import/db-init process first processes all the required entities, then all the default entities, then all the quickstart entities (or institution-specific entities if you follow the recommended process) allowing later entities to override earlier entities.

Your institution-specific entities are derived from the quickstart data (typically copy the quickstart_entities folder to an institution-specific folder and you add, remove, or modify portlets, categories, groups, PAGS groups, etc. to suit a particular institution). When going from 4.2.0 to 4.3.0 (or any release to another release) look at what changed in the entity files and incorporate those changes into your institution-specific entities.  

• Look at what has changed in required_entities and default_entities.  The git merge process described above will update these folders with the latest changes.  You'd need to look at what the changes were and incorporate those changes into your release process (typically importing new or updated entities, possibly doing ant data-delete or SQL to delete removed entities).
• When an entity exists in both default and quickstart/your-institution entities you typically do not import the default entity. You'd look at 'what was changed in the default entity and should I incorporate that change into my institution-specific entity'. Actually you'd probably look at what the change was in the quickstart entity between the versions and incorporate that into your institution-specific entity; any change to the default entity was likely also made in the quickstart entity. 
• You'd also want to look at what new additions or deletions of entities occurred in the required, default, and quickstart data. It's possible a new portlet was created and added to a layout providing new functionality you might want, as was done when the Search Launcher or notification icon was added to the header area, or what deletions occurred possibly indicating functionality change you'd want to be aware of.
• You can easily see the differences with a good diff tool. A traditional diff tool that can handle directory-level diffing would work if you check out your current release into one directory and the new release into another and you can diff the uportal-war/src/main/data folders between the two. An IDE-based tool such as intelliJ or eclipse will visually allow you to compare your current git checkout to another git branch. Again you'd probably look at what changes occurred in the quickstart data folder between the two versions and incorporate the changes you want into your institution-specific entities. Leaving the quickstart folder in your project even though it is not used is very convenient when you want to upgrade to a newer version because it gives you a base of comparison to look for the changes from the community.

Updating Tenancy with changes from Apereo

If using the multi-tenancy capabilities of the portal, in addition to updating your code and regular entities, you might also need to update the tenant data.  If you followed the standard process, you copied the sample tenant data entity files from uportal-war/src/main/resources/org/jasig/portal/tenants/sampledata to your own institution-specific location such as uportal-war/src/main/resources/tenantdata and customized them, similar to what is done with the normal quickstart data.  Look at the changes made to uportal-war/src/main/resources/org/jasig/portal/tenants/sampledata and determine which changes you would like to include in your institution-specific tenant templates.  In addition, if you have existing tenants created from the previous tenant templates, you typically want to update the existing tenant data as well. To do this the general process is:

1. Export all data using ant data-export.  The tenant data entities will be intermingled with the regular portal entities.
2. Update the existing tenant's entity files
3. Import the updates into the system.  This may be appropriate to do before or after a code update if you are trying to do zero-downtime deployments. You have to look at the changes and decide which approach is better.

Cherry-Pick Commits

The cherry-pick command can be used to merge specific commits from another branch into your vendor branch. This is useful for example if a specific bug is fixed for the next release but you need it now. You can cherry pick the commits involved in the fix into your vendor branch. Note that this is not fool proof and if the cherry-picked commits rely on a change made since the last release you have merged the merge might fail or uPortal may fail to work at runtime.

1. Determine the commit ids you want to cherry-pick. Looking at the Commits tab in the Jira Issue should show you all commits that reference the Jira ID and serve as a good starting point to determine the IDs

2. Run the cherry-pick command 

   Code Block
   language bash
   # Follow the steps in Keeping Your Fork Up To Date   # Merge in specific commits $ git cherry-pick 1a2b3c4d a1b2c3d4   # Handle any merge errors that come up $ git mergetool -y

3. Test the changes with a local build and deploy

4. Push the changes 

   Code Block
   language bash
   # push the changes to your fork $ git push origin

Upgrade to a New Release

Git can make upgrading to new releases much easier. Since all of the change history for your customizations and uPortal's development are available you only ever end up having to resolve real merge issues with very little noise. In this example we are upgrading to the uportal-4.0.6 tag.

...

Merge the new tag 

# Follow the steps in Keeping Your Fork Up To Date
 
# Checkout your vendor branch
$ git checkout myschool-master
 
# Merge in the changes that have been made up to uportal-4.0.6
$ git merge uportal-4.0.6

...

Handle Merge Conflicts 

# Handle any merge errors that come up
$ git mergetool -y

...

Push the changes 

...

...

The cherry-pick command can be used to merge specific commits from another branch into your vendor branch. This is useful for example if a specific bug is fixed for the next release but you need it now. You can cherry pick the commits involved in the fix into your vendor branch. Note that this is not fool proof and if the cherry-picked commits rely on a change made since the last release you have merged the merge might fail or uPortal may fail to work at runtime.

1. Determine the commit ids you want to cherry-pick. Looking at the Commits tab in the Jira Issue should show you all commits that reference the Jira ID and serve as a good starting point to determine the IDs

2. Run the cherry-pick command 

   Code Block
   language bash
   # Follow the steps in Keeping Your Fork Up To Date   # Merge in specific commits $ git cherry-pick 1a2b3c4d a1b2c3d4   # Handle any merge errors that come up $ git mergetool -y

3. Test the changes with a local build and deploy

4. Push the changes 

   Code Block
   language bash
   # push the changes to your fork $ git push origin

Upgrade to a New Release

Git can make upgrading to new releases much easier. Since all of the change history for your customizations and uPortal's development are available you only ever end up having to resolve real merge issues with very little noise. In this example we are upgrading to the uportal-4.0.6 tag.

1. Merge the new tag 

   Code Block
   language bash
   # Follow the steps in Keeping Your Fork Up To Date # Checkout your vendor branch $ git checkout myschool-master # Merge in the changes that have been made up to uportal-4.0.6 $ git merge uportal-4.0.6

2. Handle Merge Conflicts 

   Code Block
   language bash
   # Handle any merge errors that come up $ git mergetool -y

3. Test the changes with a local build and deploy

Push the changes 

# push the changes to your fork
$ git push origin

Updating to newer version

Updating your code with changes from Apereo

Regardless of which approach you use to update your code (see section on Cherry-Pick Commits and Upgrade to New Release), there are some things you should do.

1. Merge in the changes from Apereo (see related sections)
2. Review the updates made to uportal-war/src/main/data, in particular those made to the quickstart_entitites (which you copied and customized).  Determine which changes you would like to incorporate into your customized entities directory.  Create a plan for updating those entities in your dev, test, and prod databases (see Importing and Exporting data for information on using ant data-import).  See more on that below.
3. If you are using the multi-tenancy capabilities of the portal, review the updates made to uportal-war/src/main/resources/org/jasig/portal/tenants/sampledata and incorporate those you would like into your tenant template data set (typically you copy the sample tenant data to your own institution-specific folder and customize it).  Any existing tenants that were created from the previous data set may need to be updated.  See more on that below.

Updating your data with changes from Apereo

The database entities (in uportal-war/src/main/data) are broken into 3 tiers to theoretically allow for easier customization.  Required entities are to get the portal to run. Default entities are for basic portal functionality.  Quickstart entities are for a particular experience and are meant to be copied and customized for your institution. Some of the quickstart entities override the default entities, providing additional data such as categories and groups that are applicable to the portlets in the quickstart data set. The import/db-init process first processes all the required entities, then all the default entities, then all the quickstart entities (or institution-specific entities if you follow the recommended process) allowing later entities to override earlier entities.

Your institution-specific entities are derived from the quickstart data (typically copy the quickstart_entities folder to an institution-specific folder and you add, remove, or modify portlets, categories, groups, PAGS groups, etc. to suit a particular institution). When going from 4.2.0 to 4.3.0 (or any release to another release) look at what changed in the entity files and incorporate those changes into your institution-specific entities.  

• Look at what has changed in required_entities and default_entities.  The git merge process described above will update these folders with the latest changes.  You'd need to look at what the changes were and incorporate those changes into your release process (typically importing new or updated entities, possibly doing ant data-delete or SQL to delete removed entities).
• When an entity exists in both default and quickstart/your-institution entities you typically do not import the default entity. You'd look at 'what was changed in the default entity and should I incorporate that change into my institution-specific entity'. Actually you'd probably look at what the change was in the quickstart entity between the versions and incorporate that into your institution-specific entity; any change to the default entity was likely also made in the quickstart entity. 
• You'd also want to look at what new additions or deletions of entities occurred in the required, default, and quickstart data. It's possible a new portlet was created and added to a layout providing new functionality you might want, as was done when the Search Launcher or notification icon was added to the header area, or what deletions occurred possibly indicating functionality change you'd want to be aware of.
• You can easily see the differences with a good diff tool. A traditional diff tool that can handle directory-level diffing would work if you check out your current release into one directory and the new release into another and you can diff the uportal-war/src/main/data folders between the two. An IDE-based tool such as intelliJ or eclipse will visually allow you to compare your current git checkout to another git branch. Again you'd probably look at what changes occurred in the quickstart data folder between the two versions and incorporate the changes you want into your institution-specific entities. Leaving the quickstart folder in your project even though it is not used is very convenient when you want to upgrade to a newer version because it gives you a base of comparison to look for the changes from the community.

Updating Tenancy with changes from Apereo

If using the multi-tenancy capabilities of the portal, in addition to updating your code and regular entities, you might also need to update the tenant data.  If you followed the standard process, you copied the sample tenant data entity files from uportal-war/src/main/resources/org/jasig/portal/tenants/sampledata to your own institution-specific location such as uportal-war/src/main/resources/tenantdata and customized them, similar to what is done with the normal quickstart data.  Look at the changes made to uportal-war/src/main/resources/org/jasig/portal/tenants/sampledata and determine which changes you would like to include in your institution-specific tenant templates.  In addition, if you have existing tenants created from the previous tenant templates, you typically want to update the existing tenant data as well. To do this the general process is:

1. Export all data using ant data-export.  The tenant data entities will be intermingled with the regular portal entities.
2. Update the existing tenant's entity files
3. Import the updates into the system.  This may be appropriate to do before or after a code update if you are trying to do zero-downtime deployments. You have to look at the changes and decide which approach is better.

Contributing Fixes/Features (New Work)

...