Every now and then, the idea of contributing to Open Source Software crosses the mind of every developer. However, often, it just remains to think about it instead of actually doing something. In this blog, I want to tell the story of my first Pull Request.
1. I Do Not Have the Time For It
Do you also find good excuses for not contributing to Open Source Software (OSS)? I do. I do not have the time for it. I have a full time job, many leisure activities, I maintain my blog which takes up a significant part of my spare time. Where do I have to find the time to contribute to an OSS project? Besides that, there are many others who do so, so who is waiting for my contribution? And so on and so on. Humans are very good at finding excuses when it suits them. But is my time more valuable than the time of others? And maybe by restructuring some activities it will become possible to find some extra time? I do not have the time is all about priorities and good time management, right? And I am quite good at time management, looking at all the activities I am doing. So, why would it not be possible to contribute to OSS? Goodbye excuse…
2. Where to Get Started?
About a year ago, I got this idea of actually going to contribute to an OSS project. I searched the internet for articles how to get started and which Open Source project to choose. I can tell you: the list is huge. I am a Spring fan, so I decided to take a look at the issues of some of the Spring projects. And more specifically, the issues labeled as suited for first contribution. But, most of them were too vague for me or they sounded complicated to me. Sometimes, the issue seemed right for me, but then it was already picked up by someone else. I guess you need to be fast in order to contribute to Spring. I think because many want to contribute to Spring because it is widely popular. However, I laid the idea of contributing again to rest.
In the Summer, I always take a break from writing blogs. This seemed to be the right time to search for an OSS project to contribute to. However, something came in between and then it was already time for preparing the first blogs for September. Again, I postponed a possible first contribution.
I kept the idea warm, though. In September I saw this talk How I Started Contributing to Open Source and Why You Should Too from Marit van Dijk from the JetBrains Technology Day for Java. It did inspire me to maintain my efforts for starting to contribute. I can recommend watching this talk.
Recently, I saw a Twitter post of Eclipse Collections announcing a Learning Series in December due to the 5th anniversary of being part of Eclipse Foundation. The first Tweet in this series referred to a blog Donald Raab wrote in 2018.
Eclipse Collections@eclipsecollect
Today we are starting our Eclipse Collections Learning Series to celebrate 5 years @EclipseFdn. Day 1: Help Wanted! How the the community can contribute donraab.medium.com/help-wanted-b1…13:00 PM - 01 Dec 2020
I read the blog and it gives you the handles to get started contributing to Eclipse Collections. What attracted me the most, was the availability of katas in order to get acquainted with Eclipse Collections. A kata is a Japanese word which is used for practising martial arts. It is also being used for practising your software development skills. Victor Rentea often publishes coding katas and they are impressive to look at. But the whole idea is that you execute the katas yourselves of course. Next, I took a closer look at the GitHub repository and there were enough open issues which I thought I might contribute to. But the first step was to start with the katas when I had the time for it (where did I hear that before).
3. Time for Action
I also take a Winter break for my blog. So, now it was time to take some action! First thing to do, was to start with the Eclipse Collections kata. I started cloning the repository and followed the instructions. I started with the Pet Kata, which gives you a nice introduction to Eclipse Collections. You need to fix failing unit tests, so I first ran the tests in order to verify that they did fail initially. Next, I studied the domain model which was a fairly easy one to understand. I finished the first three exercises, verifying my solution with the one provided in the repo. It does not necessarily mean that making the test green, that you have solved it as intended. However, probably more than one solution will be ok as long as you make use of Eclipse Collections. The whole idea is to get more acquainted with the library after all.
I solved exercise 4 and noticed some minor inconsistencies between the exercise, the provided solutions and the documentation. Nothing really serious and I gues everyone will notice and understand what is wrong, but why not solve it now I noticed it?
4. My First Pull Request
I got started and tried to make my first Pull Request and we will see what will happen next.
I navigated to the repo and clicked the Fork button in the upper right corner.
The forked repository was available in my GitHub space. You will of course need a GitHub account before you can do so.
Next, I cloned the repository into my favorite IDE.
First, I created a branch (in my enthusiasm, forgot to do so in the first place). I made the necessary changes and committed them into the repository. When finished, I pushed the changes. In my GitHub page a notification was shown for creating a Pull Request.
I clicked the Compare & pull request button. You will notice that the Pull Request is going from your forked repository to the main repository of the Eclipse Collections Kata repo.
After adding information about the Pull Request, some checks were executed, one of them failed. I must admit that I did not read any instructions how to contribute.
The details button referred to a login page of Eclipse Foundations. So, first I created an account. It seems that you must accept the Eclipse Contributor Agreement, which I did. Ensure that you create an account with the mail address you use for your commits. Otherwise, the check will still fail. However, after doing so, the check still failed due to the fact that we did not have a Signed-off-by footer in our commits. Sigh. I had multiple commits (keep the commits small, you know). Thus, I needed to alter the commit messages by rebasing them. First, I removed the Pull Request and deleted the remote branch. I thought it would be better to start from scratch for this one.
I had three commit messages, so I started the interactive rebase in the local branch. Documentation how to do so is also here:
$ git rebase -i HEAD~3
An editor is opened where I changed the pick words at the beginning of the commits into edit. I saved and exited the editor. The command prompt was shown again and I entered:
$ git commit --amend
The commit message was shown in a text editor. Now I was able to add the Signed-off-by footer to the commit message:
Signed-off-by: Your real name <youreclipsefoundationsaccountmailadress>
Saved, exited and entered:
$ git rebase --continue
Next, I entered the amend command again, edited the next message and so on. At the end, I entered the continue rebase command in order to finish the rebase. I verified whether the commit messages had been altered correctly and pushed the branch. I created the Pull Request again and now all checks had been passed.
Now it was waiting for the review… I assumed that I had to wait for a week or so in order to receive a response, especially because many of us were enjoying some holiday (it was Christmas time). To my positive surprise, I received feedback the same day. I was enthusiastic about it and started the rework the next day. I agreed upon the feedback and made the changes, committed them and pushed them. Now waiting again… The same day, my first Pull Request was accepted!
5. The Next Step
In order to be prepared for making more changes, it is important to update your local repository. Therefore, it was necessary to add the original repository as a remote. I called it upstream in order to be able to distinguish it with the forked repository in my own GitHub Space.
$ git add remote upstream https://github.com/eclipse/eclipse-collections-kata.git
Next, I needed to fetch the changes, switch to the branch I wanted to update (the master branch) and rebased the changes from the upstream remote. Also, when you have already changes in your local branch, the upstream changes will be applied to your local branch and your local commits will be replayed on top of that.
$ git rebase upstream/master
The changes in the forked repository in my GitHub Space were only visible after pushing these changes to the origin remote. Remind that when you have rebased upstream changes in your local repository, you will need to force push your changes.
$ git push -f
Commit often is a practice I tend to use. It keeps the changes small and it is easier to revert a commit when necessary. The disadvantage is that you get a lengthy commit history. In order to solve this, you can squash commit your changes into e.g. 1 commit. You can also use the rebase command for that. The easiest way is to rebase with the hash of the commit before your first commit.
$ git rebase -i <hash of commit before your first commit>
A text editor will open and you leave your first commit with the pick word and for the other commits you change pick into squash. After saving the text file, a new text file is opened where you can edit the commit message for the squash commit. Exit and save the text file and you are done. Do not forget to force push your changes.
6. Conclusion
I am very glad that I persisted in my goal to contribute to an OSS project. You might think you need to climb a mountain in order to do so, but it was easier than I thought.
Some final thoughts about contributing to an OSS project:
- Finding the right OSS project to contribute to was for me the greatest challenge;
- Once you have made a first contribution, the next one will be easier;
- Contributing is an opportunity to give something back. After all, we all are using OSS libraries and take advantage of the efforts of others;
- A contribution can be simple, but it feels very rewarding when a Pull Request has been accepted;
- Write a blog about it, tweet about it, spread the word, help is wanted and requested;
- Contributing to Eclipse Collections will give me a better understanding of Java Collections in general. It is a give and take.
And many thanks to Marit van Dijk and Donald Raab for inspiring me.
Top comments (3)
Now I'm inspired by you. Thank you!
What are your tips for when you submit a pull request, and it sits there for a long time until (if you are lucky) a maintainer looks at it?
I would wait for one week and then kindly would ask in the PR when they would have time to take a look at it. But, before you submit a PR, you should take a look at how active the project still is. When there is not a lot of action, then think twice before submitting a PR.