How We Handle Pull Requests at Elastic

Getting things done at Elastic is a collaborative effort.

Our engineers work around the clock (quite literally for a distributed company) developing new products and features. It’s an immense amount of work, requiring fine attention to detail. But no matter how careful we are, we’re not perfect, and with any open source project as complex as ours, we still need the community's help to make it better.

In Solving the Small but Important Issues with Fix-It Fridays, we discussed how contributions from our community are the driving factor of our continued success in developing our products. One of the great benefits of being an open source project is that we have a large community of developers looking out for bugs and eagerly waiting for a chance to squash them.

If you’re a new member to the community and want to submit your first pull request (PR), or have questions about how the process works, you’ve come to the right place! In this post, we’ll provide an overview of how pull requests work for Elastic, what the process is when we receive one, and how to avoid common mistakes that might prevent your contribution from being implemented.

So, how do I submit a pull request?

Before you submit a PR, you need to create a fork in a GITHUB repository and make your code changes. This is usually done under your own GitHub account, which creates a copy of the source repository for you. All of our projects live in their own GitHub repository. A full list of our repositories are available on the Elastic organization page on GitHub. 

Once you’ve created a fork of a repository and changed the code, you’ll be asked if you want to create a PR to push the suggested changes to the master branch of the product repository. For example, the Elasticsearch repository seen below. To keep things simple, we'll show examples from the Elasticsearch repository throughout this post.

When you click on the “New pull request”, you’ll be greeted by our pull request template.

This template will give you the guidance that will help your PR get through the first review, so be sure to read through it since each product has its own set of criteria and documentation.

Make sure to avoid these common mistakes when submitting:

• Submitting duplicates - First, search for open PRs that already address the bug your code is attempting to fix. Duplicates are usually denied.
• Not including tests - A PR that includes code changes should include a test that illustrates the new code’s behavior. Ideally, this test should reproduce the problem the PR is fixing so that the test fails without the code, and passes when the code is applied.
• Master branch only - Make sure that any PR which changes code is made against the master branch in the relevant directory.

Once you’ve completed all the requirements spelled out in the template, click “Create Pull Requests”. Now the ball is in our court.

Triaging and labeling

The first step we take is to make sure the PR meets the requirements of a good request (as mentioned above), and if it does, to tag the PR with a label so that it ends up in the right hands for further investigation. Labels might include >bug, >feature, etc. Once the pull request has a label, it is assigned to the proper subteam to handle. From that point, dealing with the request is the responsibility of the team in charge of that area.

Beginning the process

Once the PR is labelled it is picked up by one of our developers. We try to get back to the requester as soon as possible and we ask that you have patience when submitting the PR as handling the request properly may take some time due to level and depth of requests coming in around the clock. 

Submitting documentation changes

Note: We also receive a lot of PRs that modify or request changes to our docs. This process is a lot simpler than code changes — all that’s required is to click “edit” on the Elastic docs page, make changes, and submit the request. There’s no need to fork a project and no tests required. We label these PRs “>doc” and handle them as quickly as possible.

Often, there’s more work to be done

A PR often needs to be adapted before it’s ready to merge. At this point, the PR becomes a collaborative space where discussion takes place, changes are proposed, and further commits are made.

During the review process we run tests against the PR, and the results can be seen on GitHub. Sometimes, the test will fail when the changes in the PR are applied, even if the submitted tests worked. This isn’t the end of the line though. We’ll help the contributor fix the contributed code so that all tests pass.

Code style, as well as code and naming conventions, is something we also look at in this stage. Users who submit pull requests should expect that their code will go through at least one review round. Code is never perfect (nope, not even ours!) and ready to merge when submitted — so expect some collaboration along the way.

How long will it take to commit my PR?

PRs vary in the time it takes to handle them. A simple line of code might be handled swiftly, but complex code changes will go through multiple rounds of review. If you feel that your PR has sat for a long time without any action, it’s OK to ping the ticket as a reminder it’s still active.

Committing the code

When everything is ready to go, the reviewers will add a comment with the approval action — which may be a LGTM ("Looks Good To Me") comment, or something along those lines. After the PR is accepted, an Elastic developer will merge the pull request into the master branch and then back port the change to the development branches as necessary.

So, that’s how it works — in a nutshell. Of course, pull requests vary. The process may be simple, or difficult. The only way you’ll know the process in depth is to roll up your sleeves and get in there, elbow deep.

Ready to submit your first PR? Have a look through the Elastic repositories available on GitHub, familiarize yourself with the guidelines, and give it a go. If you have any further questions about the process then head over to our Discuss forums, create a topic, and we'll be happy to help.