Becoming a Jenkins contributor: Newbie-friendly tickets

Reviewing the developer section in jenkins.io is probably the best starting point, and a reference link to keep handy. The beginners guide to contributing to Jenkins can also be useful, since it points to different repositories, tools (such as the issue tracker) and governance documents. Besides, it describes best practices for commit messages, code style conventions, PR guidelines, etc.

Once we get a general understanding of the former and want to actually start coding, we may get stuck trying to come up with something to work on.

Visiting the Jenkins issue tracker, feels like the natural next step, since it is full of potential bugs and enhancements that have already been reported by the community. However, it is quite easy to feel overwhelmed by the possibilities listed there. Bear in mind that in a 10+-year-old project like this, most of the things that are reported are tricky for a newcomer to work on. For that reason, filtering bynewbie-friendly tickets is probably the best idea.

In my case, I spent some time reviewing the newbie-friendly tickets, until I found one that seemed interesting to me and also looked like something I would be able to fix:

At this stage, when we have decided to take ownership of a ticket, it’s a good practice to let the rest of the community know that we are planning to start working on it. We can do so easily, by assigning the ticket to ourselves (see the “Assign” button below the ticket summary).

Assigning the ticket to ourselves in the Jenkins Jira will allow any other contributors to know that we are planning to take care of the ticket; and in case they are also interested in contributing to it, they will know who to reach if they want to coordinate work or ask for status. That said, it is worth mentioning that assigning a ticket to yourself does not mean that other contributors cannot work on it from then onwards. Jenkins is an open-source project and anyone is welcome to create their own PRs, so anybody can propose their own solution to the ticket. But as you can guess, if the ticket is assigned to somebody, most people will probably reach the assignee before starting to work on it.

Related to the former, it is also important to bear in mind that we should not postpone work on the ticket for too long once we have assigned the ticket to ourselves. Other potential contributors might be ignoring the ticket because they see yourself assigned to it.

Once we are about to actually start working on the ticket, it is also a good practice to click the “Start Progress” button. This action will change the status to “In progress”, signaling to the community that we are currently working on this particular ticket.

As described in the first article of this journey, the initial step to start contributing to a particular repository is to fork it to our GitHub account, and then clone it to our local computer.

As usual, in the Jenkins core repository the CONTRIBUTING file describes the necessary steps to get the repository working locally. This includes installing the necessary development tools: Java Development Kit (OpenJDK is the recommended choice), Maven and any IDE supporting Maven projects. Note that instructions to install JDK and Maven are linked in the contributing guidelines.

Once we have all the necessary tools installed and configured, we are ready to build Jenkins locally and also to run tests.

Now that I was ready to start working on the ticket, I had to review it in more detail, to fully understand the problem.

The description of the ticket I was planning to work on included two links. The first one was toa screenshot that showed the actual bug. It showed how several non-compatible plugins were being selected when clicking “All”, even though the intended behavior was to only select the compatible plugins. The second link was a reference to a code fragment that showed other validations that had to be taken into account when checking if a plugin update was compatible or not with the current installation.

Even though I had now understood the issue in better detail, I had not seen it myself live yet, so I seemed to me that the next logical step was to reproduce it locally.

To reproduce the issue locally in our computer, we can either use the local war file that we can generate bybuilding Jenkins from the source code or we can download the latest Jenkins version available and run it locally. When I worked on this ticket, the latest available version was 2.172` and, when I built if from the sources I saw version 2.173-SNAPSHOT, which was the next version, in which the community was already working on.

In general it is a good idea to reproduce bugs locally, not only to get a better understanding, but also to make sure they are actual issues. It could always be an issue happening only on the reporter’s end (e.g. some user misconfiguration). Or it could be a ticket referencing an old issue that has been fixed already. This latest possibility didn’t sound that strange to me, since the ticket was one month old. It could have been handled by someone else in the meantime, without noticing the ticket existed. Or the contributor might have forgotten to update the ticket in the issue tracker after the fix was committed.

So, for all the reasons above, I ran the latest Jenkins version locally. From a terminal, I went to the folder in which the war file was placed, and ran java -jar jenkins.war, which starts Jenkins locally on http://localhost:8080.

From the home page I navigated to the Plugin Manager (clicking the “Manage Jenkins” link in the left hand side and then selecting “Manage Plugins” in the list).

In the Manage Plugins page, the list of plugin updates appears. In my case, since I re-used an old JENKINS_HOME from an older installation, several plugins showed up in the list, requiring updates. That allowed me to test the behavior that was supposed to be failing.

When I clicked on the “Select all” option at the bottom, this is what I got:

As it had been reported in the ticket, the behavior was inconsistent. In a previous version, the behavior of the “All” selector had been changed (with the best intent), aiming to only check the compatible plugins. However, as can be seen in the screenshot, the behavior was not the expected one. Now, neither “all” nor “only compatible” plugins were being selected, since some plugins with compatibility issues were also being checked, unintentionally.

When reading the conversation in the original PR in which the behavior of the “All” selector had been changed, I saw a suggestion of having a separate “Compatible” selector, thus leaving the “All” selector with the traditional behavior. I liked the idea, so I decided to include it as part of my proposed change.

At this stage, I had a clear picture of the different things I needed to change. These included: 1) The UI, to add a new selector for “Compatible” plugins only, 2) the JS code that applied the changes to the interface when the selectors were clicked and 3) probably the back-end method that was determining if a plugin was compatible or not.

As usual, and as it is also recommended in the contributing guidelines, I created a separate feature branch to work on the ticket.

After reviewing the code, I spent some time figuring out which pieces I needed to change, both in the back-end and also in the front-end. For more details about the changes I had to make, you can take a look at the changes in my PR.

As a basic summary, I learned that the classic Jenkins UI was built using Jelly and, after understanding its basics, I modified the index.jelly file to include the new selector, assigning the function that checked the compatible plugins to this new selector, and re-using the existing “toggle” function to set all checkboxes to true in the case of “All”. I also had to modify the behavior of the checkPluginsWithoutWarnings JavaScript function, to un-check the incompatible ones, since there was now an actual “All” selector that was not there previously, and that un-check case was not being taken into account. Then, I created a new back-end Java method isCompatible, inside the UpdateSite.java class, which now calls all the different methods that check different compatibilities and returns the combined boolean result. For this change, I included an automated test to verify the correct behavior of the method, contributing to the test coverage of the project. Finally, I modified the table.jelly file to call the new back-end method from the UI, replacing the existing one that was not taking all cases into account.

As you can see, the change involved touching different technologies, but even if you face a similar situation in which you are not familiar with some of them, my advice would be carry on, don’t let that stop you. As software engineers, we should focus on our evergreen skills, rather than on knowing specific technologies; adapting to whatever framework we have to use at a given moment, learning whatever we need about the new technology to complete the task and applying cross-framework principles and best practices to provide a quality solution.

After the changes described above, the resulting UI includes a new option, and the corresponding behaviors of the three selectors work as expected:

In the contributing guidelines of the Jenkins core repository there is also a section about proposing changes, which describes the necessary steps that have to be followed in order to create a Pull Request (PR) with our change.

Furthermore, there is a PR template in the repository, which will be loaded automatically when creating a new PR and that will serve as a basis for us to provide the necessary information for the reviewers. We are expected to: include a link to the ticket, list the proposed changelog entries describing our changes, complete the submitter checklist and add mentions to the desired reviewers (if any).

In my case, I followed the template when creating my PR, completing all sections. I linked the Jira ticket, provided two proposed changelog entries, completed the submitter checklist and added three desired reviewers (explaining why I thought their reviews would be valuable). I also linked the original PR that was referenced in the ticket, to provide further context.

As stated in the contributing guidelines, typically two approvals are needed for the PR to be merged; and it can take from a few days to a couple of weeks to get them. Sometimes, one approval from a reviewer and a 1-week delay without extra reviews is considered enough to set the PR as ready-for-merge. However, both the time-to-merge and the number of approvals necessary might vary, depending on the complexity of the change or the area of Jenkins core that it affects.

After the necessary approvals have been received, a Jenkins core maintainer will set the PR as ready-for-merge, which will lead to it being merged into the master branch when one of the following releases are being prepared.

In my case, I received a review by Daniel (the reporter of the ticket and one of my “desired reviewers”) the very day I submitted the PR (April 14th). He made several very useful suggestions, which led to changes from my side. After those changes, Daniel made minor remarks and my PR got another review, which was its first approval. After a week had passed without further news, I added the remaining minor suggestions from Daniel and a few days later received another approval, to which Daniel’s final approval was added, leading the PR to be labeled ready-for-merge, being later merged the same day (April 26th).

For every new release, repository maintainers will select a set of PRs that have already been labeled ready-for-merge, merge them to master, prepare changelogs (often using the suggestions included in the PRs by the authors) and proceed with the creation of the new release. There is no additional action required from Pull Request authors at this point.

Every week a new version of Jenkins is released, so when your PR is merged, your changes will—​most likely—​become part of the following weekly release of Jenkins.

Eventually, your changes will also reach the Long-term support (LTS) release, which is a different release line, aimed for more conservative users. This release line gets synced with the weekly release by picking, every 12 weeks, a relatively recent weekly release as baseline for the new LTS release. In between, intermediate LTS releases are created only to include important bug fixes, cherry-picked from the weekly releases. New features are typically delayed until the next baseline for the LTS release is defined.

Regarding the example described in this post, it was released in Jenkins 2.175 (weekly release), soon after being merged. And will probably be included in the next LTS, which should be released next month (June 2019).