|
These instructions can be applied to any branch by replacing master with the name of the branch you're interested in keeping up to date, rel-3-2-patches for example. After performing these steps, both your local repo and your remote fork will be contain the latest changes from Apereo on the specified branch. This example, however, does not affect your Vendor Branch (see below). Be sure to read the remaining sections on this page for information on combining updates from Apereo with your local configuration, look-and-feel, and customizations.
# retrieve the updates from the upstream repository $ git fetch upstream -p # switch to the master branch $ git checkout master # merge the incoming changes into your local branch $ git merge upstream/master # now you're ready to update your fork $ git push origin master |
Or any other branch that exists in the https://github.com/Jasig/uPortal repository. If you do make a commit on a branch that is tracking a real uPortal branch and that commit is not accepted as part of a pull request you will be maintaining that customization for the rest of your fork's life. It is always better to not commit on project branches for a project that you do not have push access to and to use topic or vendor branches instead.
Determine the tag you want to use as the basis for the work, for this example we will start with uportal-4.0.5
# create the vendor branch 'myschool-master' which is based on the tag 'uportal-4.0.5' $ git checkout -b myschool-master uportal-4.0.5 # push the new vendor branch to your fork $ git push origin myschool-master |
Follow the instructions on Git Workflow for Committers for committing to your vendor branch (replace references to master with myschool-master.
quickstart_entities.location=uportal-war/src/main/data/my_entities
If you are using the multi-tenancy capabilities of the portal, you'll want to have your own version of the tenant template files so you can customize them.
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.
Run the cherry-pick command
# 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 |
Push the changes
# push the changes to your fork $ git push origin |
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.3.0 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.3.0. # NOTE: You don't specify upstream/uportal-4.3.0. That notation is for a branch not a tag. If you do something like upstream/uportal-4.3.0, you'll get an error message like # merge: upstream/uportal-4.3.0 - not something we can merge $ git merge uportal-4.3.0 |
Handle Merge Conflicts
# Handle any merge errors that come up $ git mergetool -y |
Push the changes
# push the changes to your fork $ git push origin |
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.
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.
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:
Say you've found a bug and want to contribute a fix. The easiest approach is to acknowledge that you want to contribute up front and follow these step.
Create a topic branch from the latest merged uPortal tag, this prevents unexpected changes from getting merged later on
# create branch 'UP-XXXX' based on tag 'uportal-4.0.5' $ git checkout -b UP-XXXX uportal-4.0.5 |
Once you've submitted the pull request (even better, after the pull request has been merged) merge the topic branch into your vendor branch
# checkout vendor branch $ git checkout myschool-master # merge the topic branch $ git merge UP-XXXX |
Push the changes
# push the changes to your fork $ git push origin |
Say you've fixed a bug on your vendor branch and realize you should contribute the fix back to uPortal. It isn't too late! Follow these steps to see how.
Create a topic branch from uPortal master
# create branch 'UP-XXXX' based on 'master' $ git checkout -b UP-XXXX master |
Use cherry-pick to merge the specific commits for the fix/feature into the topic branch
# Merge in specific commits $ git cherry-pick 1a2b3c4d a1b2c3d4 # Handle any merge errors that come up $ git mergetool -y |
Push your Topic Branch
# Push the branch to your fork for others to review $ git push origin UP-XXXX |