How to contribute to Tizen IVI
So you've got yourself a nice system supported by Tizen IVI, you've looked through the various Tizen IVI wiki pages that have (hopefully ) helped you set your system up and... you are now ready to start your own development on it! No matter what you will be doing, it being porting your own app to Tizen IVI, developing a nice Proof-of-Concept, building a sexy demo, etc., you may run into known (or yet unknown) issues affecting Tizen IVI packages. You may fix some along the way and if that's the case you will want to contribute these fixes back to the main Tizen IVI project... and we would definitely encourage everyone to do so! The next sections of this page describe how to make such contributions back to the Tizen IVI project. The underlying assumption is that you are not a Tizen maintainer but a contributor.
Getting ready to contribute
There are a couple of tools that are essential if you want to submit changes to Tizen; git and gbs. And if you have not already done so, now is a good time to read through the Operating System Development documentation. There is also some great documentation on how to set up your development environment which I will not repeat here.
Setting up GBS for the latest milestone
Let me just share a known good
gbs.conf file that you can use to (re-)compile packages against the final release of Tizen IVI, i.e. Tizen-IVI_3.0
gbs.conf below includes the repositories targeting systems based on Intel® Atom™ processors (both 32-bit and 64-bit). There are also specific repositories for ARM-based processors and for the Tizen IVI image used in the Tizen IVI SDK emulator. Here are the corresponding URLs:
[general] profile = profile.3.0 editor = vim [obs.tizen] url = https://api.tizen.org #user = #passwd = [repo.tizen-3.0] url = http://download.tizen.org/releases/milestone/tizen/ivi-3.0/tizen-3.0-ivi_20150201.3/repos/atom/packages/ [profile.3.0-dev] obs = obs.tizen repos = repo.tizen-3.0 [profile.3.0] obs = obs.tizen repos = repo.tizen-3.0
In this last example, we have two
profiles defined. The
3.0 profile (which is also the one used by default) will make you build your packages for the Tizen IVI 3.0-M3-Oct2014.
For those who want to track the latest development branch more closely (or simply verify that their package still builds with the latest and greatest cutting-edge code), you can easily switch to the
3.0-dev profile using the
'-P' switch (to be put after the
build command), e.g.:
gbs -c gbs.tizen-3.0.conf build -A i586 -P 3.0-dev
gbs.conf file content that can be used with previous versions of Tizen IVI, please visit the GBS configuration files for Tizen IVI
Alternatively, you can also merge this content into the main
gbs.conf file, more details on how to configure gbs here.
If you are facing some issues using GBS, please check whether that issue has already been reported here (Current GBS issues) and if not, feel free to file a new bug here under the Development Tools project and GBS component.
Strictly speaking, you do not need to install and/or use MIC unless you want to be able to generate your own Tizen IVI images.
Modifying an existing Tizen IVI package
Let's assume you have come across an issue related to the gstreamer-vaapi package and you know how to fix this. Here is how you should proceed to make these changes and push them to be accepted in Tizen IVI:
- Clone the gstreamer-vaapi package
$ git clone tizen:platform/upstream/gstreamer-vaapi
Note: The easiest way for you to know where a particular package git tree is hosted is to look into the manifest file that is published for each Tizen image that is generated. Such manifest file is put under
.../builddata/manifest on http://download.tizen.org. The manifest file for the latest Tizen IVI preview image is here for example.
- Import the commit-msg that will generate a Change-Id whenever you commit your changes
$ cd gstreamer-vaapi $ scp tizen:hooks/commit-msg .git/hooks/
The Tizen source code is managed by Gerrit and correctly using a Change-Id will greatly facilitate your submission especially if there are a few iterations needed. Important: There is more explanations as to why this is important below but in the meantime do not skip this step or you will make your own life unnecessarily over-complicated.
Switch to the git branch that you are interested in, for more details on these branches and what they mean, please take a look here. You'll most likely want to use the
tizen branch these days.
$ git checkout tizen
As a safety measure and to make sure my environment is sane, I always try to build the package I have just cloned (although that is not strictly required), which in its simplest form is as simple as issuing:
$ gbs build
Here is a more complete GBS User Guide. You will only really use two commands from gbs, namely
gbs build and maybe
Now that you are confident your environment is properly set up, you can make the modifications that fix a particular issue. You will most likely want to test a few iterations of your modifications before committing the changes in Git and submitting them to Gerrit. To do that, simply rebuild the package as follows:
$ gbs build --include-all
That will generate an RPM that you can install on your test system and that includes all the changes that you have not commited at this stage. Note that the package version does tend to fall behind when you build locally versus what's in the repositories so it's a good idea to force the installation of that particular RPM on your test (target) system.
Transfer the binary RPM to your target/test system (e.g. USB stick) $ zypper in -f <your-package-rpm>
Once you're happy with all your changes, commit them:
$ git commit -a -s
Write up a useful commit message, including the bug ID it fixes (e.g. TIVI-XXX) if relevant. If you run
git log again, you will see that a Change-Id has been created and appended to your commit message.
You are now ready to push your changes for review in Gerrit:
$ git push origin HEAD:refs/for/<branch-name>
<branch-name> is to be replaced with the particular git branch you've been working on, so in our example that would:
$ git push origin HEAD:refs/for/tizen
A four-digit Gerrit review ID will be issued and you can see it using https://review.tizen.org/gerrit/XXXX where XXXX is that 4-digit ID.
Important note: You are not expected to modify the
packaging/<package-name>.changes file (which would be done using
gbs changelog), the maintainer will do this globally for the package, your responsibility is to make sure your commit message is clear, concise and includes all the relevant information.
The next steps is that your changes will be reviewed by the developers/maintainers in Gerrit until your changes are +2'ed and finally merged. It may happen that you have to go through a few iterations of review and re-factoring of your changes before they get accepted. To effectively do this, you can proceed as follows:
- Make more changes taken the feedback into account
- Test your latest changes (as described above)
- When your new changes are ready, amend your previous commit:
$ git commit -a --amend
If you also want to update your commit message you can use:
$ git commit -a -c --amend
This could be useful in case you did not read the instructions above properly (but that would never happen of course... ;-) ) and no Change-Id was initially added to your commit message. If that is the case, check in the Gerrit review in progress (https://review.tizen.org/gerrit/XXXX) what Change-Id was automatically assigned and insert it at the end of your commit message.
$ git push origin HEAD:refs/for/<branch-name>
This re-uses your last git commit ID and therefore also preserves the Change-Id included in the commit message (that was created automatically thanks to the .git/commit-msg file you copied earlier). This is really important so that Gerrit will immediately match this new push to the existing Gerrit review that's in progress. Otherwise, in case you did not copy the .git/commit-msg file earlier on (in other words, if there is no Change-Id in your commit message), then Gerrit will generate a new patch for every new push which means you would have to abandon the previously pushed change, reset your git repo to the last commit before yours and re-create a new commit to be pushed for review which is a bit of a convoluted process and also does not track properly the various reviews/comments.
- Once the developers/maintainer are happy with your changes, they will +2'ed them and they will be merged in the package codebase and will show up soon in Tizen IVI!
- Congratulations!! You have just made your first successful contribution to the Tizen IVI project... and we hope this is the just the beginning of a long series!
If you want to keep your local copy of that git tree, now is a good time to run:
$ git pull
This will make you pull the latest updates that include your patch :-)