As a software engineer, for many years I have used open source software (frameworks, libraries, tools…) in the different companies I have worked at. However, I had never been able to engage in an open-source project as a contributor, until now.
Since I made my first—ridiculously simple—commit into Jenkins, six months ago (in September, 2018), I have been attempting to contribute more to the Jenkins project. However, contributing to open-source projects is, in general, challenging. Especially to long-lived projects, with a lot of history, legacy code and tribal knowledge. It is often difficult to know where to start and also difficult to come up with a plan to keep moving forward and contributing regularly, and in more meaningful ways over time.
When it comes to the Jenkins project, I have encountered challenges that others trying to get into the community are likely to encounter. For that reason, I have decided to go ahead and share my journey of becoming a more engaged Jenkins contributor.
I plan to publish roughly 1 post per month, describing this journey. I will attempt to start contributing to the pieces that are easier to start with, transitioning towards more complex contributions over time.
Where to start
jenkins.io
To become a Jenkins contributor, the most obvious place to start looking at is jenkins.io. In the top navbar there is a Community dropdown, with several links to different sections. The first entry,Overview, takes us to the “Participate and contribute” section.
In this section we get lots of information about the many ways in which we can engage with the Jenkins project and community. Even though the intention is to display all the possible options, allowing the reader to choose, it can feel a bit overwhelming.
The page is divided into two columns, the column on the left shows the different options to participate, while the column on the right shows the different options to contribute.
Suggestions to Participate
In the left column of the “Participate and contribute” page, there are several ideas on how to engage with the community, ranging from communicating to reviewing changes or providing feedback.
One of the pieces that got me confused at first in this area were the communication channels. There are many different channels for communication. There are several mailing lists and there are also IRC and Gitter channels.
During my first attempts to get involved, I subscribed to many of the mailing lists and several IRC and Gitter channels, but I quickly noticed that there is significant communication going on; and that most threads in the most active lists and channels are specific to issues users or developers have. So, unless your goal is to support other users right away (if you are an experienced Jenkins user already it might be the case) or you plan to ask questions that you already have in mind, I would advise against spending too much time on this at first.
Even though it is great to see how the community members support each other, the amount of communication might be overwhelming for a newcomer, and if you are also trying to contribute to the project (either with translations, documentation or code), following these conversations might not be the best way to start.
Suggestions to Contribute
In the right column of the “Participate and contribute” page there are several ideas on how to contribute, mostly grouped into: writing code, translating, documenting and testing.
In following posts, I will be going through all of these types of contributions, as well as through some of the suggestions to participate, which include reviewing Pull Requests (PRs) or providing feedback (either reporting new issues or replicating cases other users have already described, providing additional information to help the maintainer reproduce and fix them).
My first contribution in this journey
When looking at the “Participate and contribute” page, I noticed a couple of things in that page that I could help improve. And I was actually planning to pick one of those as the first example of a contribution for this post. But when I was reading the contributing guidelines of the repository, I found an even easier contribution I could make, which I thought would be a great example to illustrate how simple it could be to start contributing. So I decided to go ahead with it.
The website repository
In the ”Document” section there is a link to the contributing guidelines of the jenkins.io repository. The CONTRIBUTING file is a common file present in the root folder of most open-source-project repositories.
Following the link to that file, I reached the jenkins.io repository, which is the one that contains the sources for the corresponding website—which also includes this blog. And, in fact, the contributing file was the first file I wanted to review, in order to learn more about how to contribute to the website.
Found a broken link
When reading the contributing file, I learned about the Awestruct static site generator, which is the tool used to transform the AsciiDoc source files in the repo into a website. However, when I clicked the link to learn more about it, I noticed it was broken. The domain had expired.
Why not fix it?
This was the opportunity I chose to show other newcomers how easy it can be to start contributing.
Forking the repository
The first step, as usual, would be to fork the repository and clone it to my machine.
Applying the change
The next step would be to apply the change to the corresponding file. To do so, I created a new branch “alternative-awestruct-link” and applied the change there:
Making sure everything builds correctly and tests pass
Even though in this case my contribution was not to the actual website, but to the contributing guidelines (and for that reason was unlikely to break anything), it is a best practice to get used to the regular process every contribution should follow, making sure everything builds correctly after any change.
As stated in the contributing guidelines themselves, in order to build this repository we just have to run the default “make” target, in the root of the repository.
Once the command execution finishes, if everything looks good, we are ready to go to the next step: creating the PR.
Creating the PR
Once my change had been committed and pushed to my repository, I just had to create the PR. We have an easy way to do so by just clicking the link that we get in our git logs once the push is completed, although we can create the PR directly through the GitHub UI, if we prefer so; or even use “hub”, the GitHub CLI, to do it.
In this case, I just clicked the link, which took me to the PR creation page on GitHub. Once there, I added a description and created the PR.
When a PR to this repository is created, we notice there are some checks that start running. Jenkins repositories are configured to notify the “Jenkins on Jenkins”, which runs the corresponding CI pipelines for each repository, as described in the corresponding Jenkinsfile.
Once the checks are completed, we can see the result in the PR:
And if we want to see the details of the execution, we can follow the “Show all checks” link:
I have contributed!
This contribution I made is a trivial one, with very little complexity and it might not be the most interesting one if you are trying to contribute code to the Jenkins project itself.
However, for me, as the contributor, it was a great way to get familiar with the repository, its contributing guidelines, the technology behind the jenkins.io website; and, above anything else, to start “losing the fear” of contributing to an open source project like Jenkins.
So, if you are in the same position I was, do not hesitate. Go ahead and find your own first contribution. Every little counts!