Contribute to Android – My repo/git adventure

Note (29 july 2009): found out that the merge action is generating a empty change commit (which depends on change 9828 and is needed by my change). I started a discussion at http://groups.google.com/group/repo-discuss/browse_thread/thread/c9c29d4eca6c7989 and got a response that I should use git reset. Updated this post to reflect the new procedure

While I am still working on some blogpost about flashing the Android Dev Phone and adding the Google Apps, I was wondering if I can easily contribute some changes to the Android source tree. In my blog about getting the Android Source, I applied a patch and edit the extract-files.sh and AndroidBoard.mk inside vendor/htc/dream by hand so that all proprietary used for the HTC Dream are extracted from an ADP and added to your own Android system image. But wouldn’t it be nice when you just apply one patch and do not have to edit the files by hand. This is where the journey begins.

In the beginning…

Before making the changes to both scripts I started with a clean local source tree. I got the source (android-1.5r2 as described here) together with the specific htc vendor parts (by using the local_manifest.xml). After repo sync is finished, it is time to perform the changes which will result in a new patch.

When repo was asking for my name and emailaddress, I used my gmail account. If you don’t use a gmail account you cannot post changes to the source tree.

Patch 9828

I knew that change 9828 already updates the two script files (but there are still parts missing). I decided to apply this patch to my local source tree with the idea that it will be an extension on this patch

repo download platform/vendor/htc/dream 9828

Because I want to make an extension on this patch I should make a local branch first containing this change which can be later merged to the developer branch which will contain the additions to both script. So you can skip this step if your change does not depend on another patch.

git checkout -b branch9828

This will make a local branch called branch9828

Contribute steps

At http://source.android.com/submit-patches is described how to submit patches. I used these steps as my guide in the repo/git adventure. But like an outdated tourist guide book I found some rocks on my path.

Starting a topic branch

Before I can make my changes I should start a topic branch on my local work environment. This topic branch is used to keep changes together. You can have multiple topic branches in your local work environment. But keep changes seperate so that the use of a patch is clear.

Using repo start default (where default is the topic branch name, but you can name it whatever you want) does not work for me. You should also add the project which you are going to change (or supply the -all argument but I think that you should really limit it to a project to keep things seperately). The change I want to contribute is in the platform/vendor/htc/dream project

repo start default platform/vendor/htc/dream

This command will not give you back any feedback. On the other way, if you use it wrong it will give you feedback.

Merging the 9828 branch

The new change will be an addition on the 9828 step. I already created a local branch for those changes and I want to merge those to my default local development branch. This way I can use repo upload to send my change to the review server. So you can skip those steps if you don’t depend on unapproved changes

git reset--hard branch9828

HEAD is now at b15e33c... Added more proprietary libraries.

Because the local branch9828 is not needed anymore, I deleted it

git branch -d branch9828

Deleted branch branch 9828

Editing the files

With a texteditor I changed and saved both files. I will not place the changes I made to both files here in this blogpost because you can see them easily by going to https://review.source.android.com/Gerrit#change,10813 and look at the Side-By-Side diffs.

Staging changes

The steps at http://source.android.com/submit-patches describes that you should perform a git add to “stage” the changes for the next commit. This is optional when you don’t add files. So in my case I did not performed this step

Change status

After I changed both files I can see the status of the current branch by executing

repo status

You will get some kind of result (this is the repo status result after changing both script files)

# on branch default
project vendor/htc/dream/                       branch default
 -m     AndroidBoard.mk
 -m     extract-files.sh

This status reports makes clear that both files are changed (-m before each line). But what are the exact changes? You can use git diff to see detailed information.

git diff

diff --git a/AndroidBoard.mk b/AndroidBoard.mk
index 7f82037..58e2cd0 100644
--- a/AndroidBoard.mk
+++ b/AndroidBoard.mk
@@ -85,3 +85,8 @@ PRODUCT_COPY_FILES += \
 PRODUCT_COPY_FILES += \
        $(proprietary)/tiwlan.ini:system/etc/wifi/tiwlan.ini \
        $(proprietary)/Fw1251r1c.bin:system/etc/wifi/Fw1251r1c.bin
+
+PRODUCT_COPY_FILES += \
+        $(proprietary)/lights.msm7k.so:system/lib/hw/lights.msm7k.so \
+        $(proprietary)/AudioPreProcess.csv:system/etc/AudioPreProcess.csv
+
diff --git a/extract-files.sh b/extract-files.sh
index ccd78a3..7318500 100644
--- a/extract-files.sh
+++ b/extract-files.sh
@@ -31,4 +31,7 @@ adb pull /system/lib/hw/sensors.trout.so proprietary/sensors.t
 adb pull /system/etc/wifi/Fw1251r1c.bin proprietary/Fw1251r1c.bin
 adb pull /system/etc/wifi/tiwlan.ini proprietary/tiwlan.ini

+adb pull /system/lib/hw/lights.msm7k.so proprietary/lights.msm7k.so
+adb pull /system/etc/AudioPreProcess.csv proprietary/AudioPreProcess.csv

Committing changes

Next step is to commit the changes. Because I did not add new files I run the command

git commit -a

Commit will find the changes and the default texteditor will be opened for providing a comment (in my case it is gedit). There is a comment template which I changed to

Added more proprietary libraries.

The Led light of the HTC Dream should work when
extra libraries are extracted from the HTC Dream and
added to the system image.

The wlan.ko is not extracted (comparing to change 10501).
This is already part of the project or can be build from
source.

Saved and close the file and the commit command will result with a message like

Created commit 6aab35e: Added more proprietary libraries.
 2 files changed, 8 insertions(+), 0 deletions(-)

Note: If you provide an empty comment then the commit will be aborted

Contributor Agreement and public SSH key (only for the first time)

Last step is to upload the changes to the review server. Because it is the first time I want to post some changes to the Android Source tree I have to complete a Contributor Agreement (https://review.source.android.com/Gerrit#settings,new-agreement) to give permission that your changes can be distributed to others. I logged in with my Google Account (the one I also used when getting the source from repo) and because I am an individual I selected the Individual Ageement Type, filled in the form and submitted it.

Because you signed this agreement it is important that repo knows who you are by providing a public SSH key. The steps for creating this key should only be executed once and are stored (as default) inside the ~/.ssh directory. I am not going to describe the steps of creating this SSH keys because those are clearly written down in a step by step manual at http://github.com/guides/providing-your-ssh-key

Note: xclip (a tool for sending the content to the clipboard) can be installed on ubuntu with: sudo apt-get install xclip

The contents of the public key (which is on you clipboard) should be added to your personal page on the review server (https://review.source.android.com/Gerrit#settings,ssh-keys, maybe you should login with you Google Account). Paste the content of the clipboard inside the Add SSH Public Key box and press Add.

Note: don’t mind the / characters inside the clipboard content. Adding the messy content of the clipboard will work.

After the key is added it will be shown in the list (https://review.source.android.com/Gerrit#settings,ssh-keys).These steps should only repeated again I you want to use a different key when for example you are using a different environment.

Uploading changes

Even we had to take a sidepath (for creating the SSH key), the last step is to upload the changes. It is possible that in the meantime someone is working at the same files. So before uploading, synchonize the source

repo sync

Upload the changes by executing

repo upload

If you are working on multiple changes and have multiple topic branches, some editor window will be shown. In my case I only have one topic branch so I get a prompt if I want to upload the sources

Upload project vendor/htc/dream-open/:
  branch default ( 4 commits, Tue Jul 28 07:05:46 2009 +0200):
         0c35fa84 Add /system/lib/libhtc_acoustic.so to the list of needed proprietary files. Without it, audio does not play in Android 1.5.
         c93fac29 Whoops, fix file permission touched by editor.
         b15e33c5 Added more proprietary libraries.
         f2a9ebde Added more proprietary libraries.
to review.source.android.com (y/n)? y
Counting objects: 7, done.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 653 bytes, done.
Total 4 (delta 3), reused 0 (delta 0)
To ssh://johan.c.de.koning@review.source.android.com:29418/platform/vendor/htc/dream-open
 * [new branch]      default -> refs/for/cupcake

New Changes:

https://review.source.android.com/10813

--------------------------------------------

[OK    ] vendor/htc/dream-open/ default

Changes are submitted and a url is given back. On this url you can find details about the change made (like the Side-by-side diffs). The result given back also makes clear that this change depends on other changes.

And they lived happily ever after….

So what’s next? I uploaded the change to the review server. This does not mean that when you do a repo sync you will automatically get this change. No, like the server name said, it should be reviewed first. But by who and when? I don’t know. In the meantime you can use these changes by applying them on your local source

repo download platform/vendor/htc/dream 10813

Looks like there will be a sequel of this journey: Contribute to Android – Judgement of the reviewer