Contributing to OSS

15 Mar 2017

This is going to be a series of posts that highlight my experience with contributing to OSS in general, but focusing on Polari in particular.

I’ve been using GNOME for a while now, a long while. The project is a masterpiece of clean and fresh design, simplicity, and gets out of your way while working. Many of the applications included in the GNOME ecosystem follow this paradigm.

One of these applications is Polari, an IRC client. It has a nice minimalist design, is functional and clean yet usable. In short, it does what is needed to get a user up and chatting quickly and with minimal fuss.

It did have a downside though, as I discovered; long user nicknames in chat could cause issues.

What was happening as a result of the above is two things:

This issue was enough for me to stop using particular channels where that one user participated. This of course meant I wasn’t using those channels, and that is not good enough for anyone.

So I’d found what would be classed as a gronked/needed feature, and set out to fix it.

How easy is it to contribute?

I have to say that GNOME is one of the more friendlier and easier larger projects to contribute to. There are many well written newbie guides to peruse such as (this one for Gnome Builder)[https://wiki.gnome.org/Apps/Builder/Contribute] - which rapidly rising to be the chosen development environment for Gnome applications. And the GNOME (code contribution guide)[https://wiki.gnome.org/Newcomers/CodeContributionWorkflow].

Essentially your workflow (for code contributions) will look like:

  1. Set up git
  2. Checkout the code repository for your chosen project
  3. Choose a bug to work on
  4. Create a branch for the work you do (with a name relating to the bug you’re working on)
  5. Once work is completed, submit a patch for review

It’s as simple as that. Really. Many other OSS projects will have a similar workflow to this, and in the case of projects hosted on github, you will only need to submit a pull request once you complete the work.

The Importance of Commit Messages

This is something I think a lot of people get wrong when they first start off - commit messages.

If you look at a git log, on github for example, you will usually see only the first line of a commit message. For this reason, it is very good practice for you to get in the habit of writing a short, concise description of the commit that fits a single line - and then expand on that line in a new paragraph.

Why? Not only will this help others when analysing git logs, but it will help you in the long run by making it easy to see what was changed, why, and where. One of the best blog posts I’ve found that expounded on this is by (Chris Beams)[https://chris.beams.io/posts/git-commit/] - make sure to check it out.

Some projects have a guide for how they prefer their commit messages to be written (normally a plain text file named CONTRIBUTING); if this is the case, be sure to follow it.

Example of GNOME preferred commit message;

Short title describing your change

Context of the bug/issue/change.

Problem that it intends to fix and when happens.

Fix.

Bugzilla link

The First Task

The first thing I wanted to do was shorten the nicknames that went over a certain limit. But before I could start, I needed to checkout the source, and build it to ensure I could test the work I do.

For Polari, this was made dead easy by (Gnome Builder)[https://wiki.gnome.org/Apps/Builder] which Christian Hergert works on full time. One of the powerful features of Builder, is the ability to compile and run programs in a (Flatpak)[http://flatpak.org/] environment - for GNOME you can use either stable or nightly Flatpak enviroments (flatpak in itself is an incredible piece of work).

There are other ways to compile GNOME software, such as using Jhbuild (which I never got working due to repo errors), and in the case of openSUSE, using the (Open Build Service)[https://build.opensuse.org/]. For non-GNOME projects, the project itself will generally include some form of instruction on how to build the software from scratch.

Other Ways to Contribute to OSS

You don’t have to be a programming wiz to contribute to the world of OSS. There are a great deal of other ways you can help:

And this is just a short list! Generally speaking, if you think a project could benefit from something you can provide, go ahead and do it! Contact those people responsible for the project via their chosen means, tell them what you can offer, and go from there.

Onwards!

Armed with Builder, Flatpak, and the source to Polari, I got to work and started reading the code to see what did what. And this is where I will leave this post for now.

Coming up next will be topics such as: code reading, importance of documentation, maybe some advice on using git, and how/what I did with Polari.

Tweet me @rustedLuke if you like this post.

Tweet
comments powered by Disqus