First contribution to Haiku

In this article, I will explain the whole process in case of new contribution to the source code.

Contributing can be done at different levels : fundraising, testing, reporting bugs, creating documentation, spreading the words :)

If you are a developer correcting bugs or developing new features is also possible.

Initial idea

I was looking for a feature which was missing in the operating system.

However, as it was my first contribution and commit, I need something very simple to do in the code.

Indeed what is complex for a first attempt is to follow the process from the initial setup until the validation of the contribution.

I had a first idea to improve Pe editor, because something is very annoying today.

With the current color defaulting, the search of a string like "include" appears with a yellow border like below, when the focus is not in the main window :

Do you see it ?

It's the line with the #include <Bitmap.h>

Well, it's a joke you would ask ?

No, it's the way it's working today...

Not very good for a default code editor.

When the main window is having the focus, it's displayed more clearly like below :

So my idea was to comment the code which was used when the focus is not in on the editor's window.

As this application is available in the default Haiku's installation, I thought it was part of Haiku sources.

But I was wrong : Pe editor sources are only available in the Haiku archives repo.

So I decided to find another idea (I have however proposed a PR on Haiku archives repo to solve the issue described).

Let's review now how Icon-O-Matic application is working today.

For instance, in case of Shape, you can :

• Add a shape
• Duplicate
• Remove a shape

Now regarding the Transformer, you can :

• Add a transformer
• and Add a transformer...
• and Add a transformer... ??

Really strange, where is the Remove feature ?

I don't know the reason, but there's no way to remove, so let's do that proposal !

Let's add a new "Remove" menu entry for the Transformer like this :

Pre-requisite

The reference page I used to understand how to do that was the "Pushing patches to Haiku 101" on the official website.

I my case, I will use Haiku to contribute to Haiku, as it is my main - and only - system on my NUC Intel.

I advice you to follow this page carefully, if you want to contribute for the first time to Haiku's sources.

What is important to understand is that it's very easy to retrieve the source code and compile it for your own usage, as it can be done through the github repo.

However for contribution, it's more complex, as you need to use the Gerrit repository to retrieve the source code :

And you will also need to have access to Gerrit code review portal to follow the contribution's validation process :

Before cloning the gerrit repo, I need to define my user name (a nickname) and my email address:

git config --global user.name "DigitalBox98"
git config --global user.email "email@example.com"

Once done, this setup is saved in the "/boot/home/config/settings/git/config" file.

Next I add to connect to Gerrit code review portal.

For that, I'm using my github account to login :

Having a github account is necessary according to the official website.

Next, I need to generate a ssh key of type ed25519 for the gerrit repo authentication :

ssh-keygen -t ed25519

The key is inside the "/boot/home/config/settings/ssh" directory :

• id_ed25519.pub for the public key
• id_ed25519 for the private key

The public key is the one which is needed to put on Gerrit portal.

In the account settings, in the "SSH Keys" part, I had to paste the content of my public key and validate by clicking on "Add new ssh key" :

Once the public key is added I can see it validated :

Going back to Haiku, I remember having authentication issue preventing to clone the Gerrit repo.

So the below commands might be useful :

eval "$(ssh-agent -s)"
ssh-add /boot/home/config/settings/ssh/id_ed25519
ssh-keyscan -t ed25519 git.haiku-os.org >> /boot/home/config/settings/ssh/known_hosts

Now checking if the authentication is recognized with this new public key : ssh -T digitalbox98@git.haiku-os.org
**** Welcome to Gerrit Code Review ****
Hi DigitalBox98 DigitalBox98, you have successfully connected over SSH.

Yes ! That's fine.

Now, I can clone the "buildtools" and "haiku" repo :

export USER=digitalbox98
git clone "ssh://$USER@git.haiku-os.org/buildtools" && curl -Lo "buildtools/.git/hooks/commit-msg" https://review.haiku-os.org/tools/hooks/commit-msg
git clone "ssh://$USER@git.haiku-os.org/haiku" && curl -Lo "haiku/.git/hooks/commit-msg" https://review.haiku-os.org/tools/hooks/commit-msg
chmod +x haiku/.git/hooks/commit-msg

Replace the line with the export command with your username.

Then as indicated on the website, the below commands will install a Git hook that will automatically generate Change-Id’s :

curl -Lo "haiku/.git/hooks/commit-msg" https://review.haiku-os.org/tools/hooks/commit-msg
chmod +x haiku/.git/hooks/commit-msg

Ok I'm now ready to start my enhancement !

Developing and testing

Before starting any development, it's recommended to read the coding guidelines on the official website.

As I don't know anything on how Icon-O-Matic works, I'm first looking for the word "Transformer" as it's the item I would like to enhance.

cd Document/C/haiku/src/apps/icon-o-matic
grep -nrw "Transformer" .

Interesting :)

The TransformerListview can be a good candidate.

Let's confirm this by debugging the application.

I used the method explained in Debug official haiku apps article to generate a debug version of the application, and then I start debugging with QtCreator.

After a few attempts, breakpoints and code reading, I have identified that :

• SetMenu() is building the menu of the TransformerListView

• MessageReceived() is handling user's interaction for the menu

• TransformerListView.h is containing the private menu items (BMenuItem) :

After several code changes, attempts and testing, the below changes were done :

• For "TransformerListView.h" :
  • add the BMenuItem for the "Remove" feature

• For "TransformerListView.cpp" :

• add an enum to handle the message for the "Remove" feature

• handle the remove message and do the removal :

• enhance the menu setup to add the "Remove" entry associated to the removal message :

Quite simple, that's what I wanted for my first contribution :)

Sending the patch

In icon-o-matic source directory, I then add the two modified files for my contribution :

git add gui/TransformerListView.cpp
git add gui/TransformerListView.h

Then I do the local commit :

git commit -a -m "Icon-O-Matic: Add remove menu on Transformer"

And finally I push that commit to the Gerrit remote repository:

git push origin HEAD:refs/for/master -o topic="Icon-O-Matic enhancement"

The contribution process can be now followed on the Gerrit portal via the Dashboard :

I can see here the various comments and proposals to enhance my patch until it's validated.

The Gerrit tool is nicely done, however at the beginning it was a bit disturbing as there were many information available on the dashboard, and I was not sure what to do in the process :)

Correcting the patch

That's were things got complicated for me..

I had to change of fews things like typo errors.

So again, I added my changes in the commit :

git add gui/TransformerListView.cpp
git add gui/TransformerListView.h

But if I remember correctly, I've done a commit without amend which seems to be mistake in the process:)

git commit

And then pushed my changes :

git push origin HEAD:refs/for/master

I made this mistake several times (3).

With the help of the reviewers, I add to use the below command :

git reset HEAD~3

Then I added again my changes :

git add gui/TransformerListView.cpp
git add gui/TransformerListView.h

Then a commit **AMEND** to make things working better :)

git commit --amend

Then pushed the commit :

git push origin HEAD:refs/for/master

And then it was ok !

Approval

Once all these last adjustments were completed and the reviewers confirmed it was OK, the Gerrit details were updated:

Then my changes were merged into the official sources and the result was visible on the Haiku website's source activity:

What is great is that everyone can see the full audit log of the changes at the URL https://cgit.haiku-os.org/haiku/log/ :

In case you use Haiku's nightly version, you should now have access to this new "Remove" feature on Transformer:

I hope this article will give idea to additional people to contribute to the Haiku sources :)