Getting ready to contribute to #OpenUI5 – Keeping a fork up to date
Being a Contributer
In my recent talk at SAP Teched in Las Vegas on writing SAPUI5 applications I made a comment about contributing to the OpenUI5.
There were a couple of reasons for this:
1. Contributing to an open source project will be a cool thing to do
2. You will learn a lot about OpenUI5 in the process even if you don’t actually submit anything.
With this in mind there are several ways you can contribute and they are outlined here.
All of those are great things to do and I drop into the forums here and at stack exchange to see how I can help others and learn myself to see what people are struggling with.
If though you are going to take the final step and contribute code then we need to have a local fork of OpenUI5.
Firstly you have to make sure your local setup is working and review the contributing guides
But before we get to this we have to fork OpenUI5 and clone it to our local machine.
Well, that is pretty easy and I have done this a couple of times only to find that UI5 is marching on and every other day the core UI5 team are committing to the master branch.
So how to keep our clone up to date.
That is what we are going to cover in this blog.
Firstly fork OpenUI5 to your own account. This is as simple as going to SAP/openui5 · GitHub and clicking on the fork button.
Then you need to clone that fork to your own computer. You can do this step with the UI versions of Github for windows but for the following steps you are going to need the command line as there isn’t a UI option to keep a fork up to date.
09:18:55 /var/www$ git clone firstname.lastname@example.org:sqrc/openui5.git Cloning into 'openui5'... remote: Counting objects: 220479, done. remote: Compressing objects: 100% (207/207), done. remote: Total 220479 (delta 113), reused 0 (delta 0), pack-reused 220218 Receiving objects: 100% (220479/220479), 82.91 MiB | 259.00 KiB/s, done. Resolving deltas: 100% (125255/125255), done. Checking connectivity... done.
Then you need to set your upstream repo – the one that you cloned from
09:25:32 /var/www$ cd openui5/ 09:25:50 (master) /var/www/openui5$ git fetch upstream fatal: 'upstream' does not appear to be a git repository fatal: Could not read from remote repository. Please make sure you have the correct access rights and the repository exists. 09:25:51 (master) /var/www/openui5$ git remote -v origin email@example.com:sqrc/openui5.git (fetch) origin firstname.lastname@example.org:sqrc/openui5.git (push) 09:26:18 (master) /var/www/openui5$ git remote add upstream email@example.com:SAP/openui5.git 09:28:14 (master) /var/www/openui5$ git remote -v origin firstname.lastname@example.org:sqrc/openui5.git (fetch) origin email@example.com:sqrc/openui5.git (push) upstream firstname.lastname@example.org:SAP/openui5.git (fetch) upstream email@example.com:SAP/openui5.git (push)
I first tried to fetch my upstream but none existed. I then checked what the remotes are set to and then added the upstream repo to the OpenUI5 repo.
Now when I check my remotes I have an origin and an upstream.
Now when I fetch from upstream I will pull in the new branches I don’t have in the clone.
09:28:18 (master) /var/www/openui5$ git fetch upstream From github.com:SAP/openui5 * [new branch] gh-pages -> upstream/gh-pages * [new branch] master -> upstream/master * [new branch] rel-1.26 -> upstream/rel-1.26 * [new branch] rel-1.28 -> upstream/rel-1.28 * [new branch] rel-1.30 -> upstream/rel-1.30 * [new branch] rel-1.32 -> upstream/rel-1.32 09:28:36 (master) /var/www/openui5$
Now you can merge the upstream with master and provided you haven’t done anything on master that should be pretty painless fast forward merge
12:08:42 (master) /var/www/openui5$ git merge upstream/master Updating c1f7be6..3180cd8 Fast-forward src/sap.m/src/sap/m/ActionSheet.js | 12 +- src/sap.m/src/sap/m/NotificationListGroup.js | 29 ++- src/sap.m/src/sap/m/NotificationListItem.js | 6 +- src/sap.m/src/sap/m/NotificationListItemRenderer.js | 4 +- src/sap.m/src/sap/m/P13nColumnsPanel.js | 185 +++++++++++++++--- src/sap.m/src/sap/m/ViewSettingsDialog.js | 129 +++++++++---- src/sap.m/src/sap/m/messagebundle.properties | 24 +++ ...
Now all you have to do is regularly pull from upstream with git fetch upstream and merge with git merge upstream/master
Your github fork though is behind master.
Note that at the bottom of this image it states that ‘This branch is 42 commits behind SAP:master’
To fix this once your local clone is up to date with the commands above you just need to git push and you are done.
Now: ‘This branch is even with SAP:master’
You could even add these into an alias to make it a single command.
Set up a local fork of OpenUI5 and get ready to contribute.
Two bonus links from githubs documentation if you are looking for more info on this:
(UPDATE: I just realised my title of keeping a clone up to date is not quite strictly correct – it is the fork we are keeping up to date and I have changed it.)
(UPDATE2: Here is a nice bash alias to do all this in one step. Don’t use ubuntu? Time to upgrade then 😉 )
alias uui5=”cd /var/www/openui5;git checkout master;git fetch upstream;git merge upstream/master;git push;”
thanks for article, Nigel.
is there any particular reason or disadvantage if I switch to the sequence below?
on a sidenote, you may want to take a look at the part of the article where it says
it is unclear whether you meant "do the fork of OpenUI5 first, then clone the fork to local machine" or "clone the OpenUI5 repository to local machine, then make a fork of it". there will be a difference in semantic of the remote names eg. which is the 'origin' vs 'upstream'