How to file a GitHub issue the best way

From bug reports to feature requests, we rely on the Elastic community to keep our projects chugging. If you’re new to using the Elastic Stack, contributing to our project by submitting a GitHub issue might be a little bit nerve wracking.

You may be asking yourself: Is the process complicated? What if I get lost along the way? What if I make a mistake?

Don’t worry! We’re here to help. This blog is part of a series of posts in which we cover several aspects of how we handle things through GitHub — from pull requests, to how we tackle lingering issues with our Fix-It Fridays initiative.

While each product in the Elastic Stack has their own CONTRIBUTING.MD file, this post will highlight best practices for a few scenarios in which you might find yourself when contributing to our larger project as a n00b.

Bug Fixes

Scenario one: you’re using a product in the Elastic Stack and you come across a bug.

Well, before you head to GitHub and submit an issue, make sure you’re using the latest version of the Elastic Stack. This avoids submitting an issue for a bug that’s been fixed in a newer release. However, if you find a bug in a previous version that hasn’t been fixed in a newer version of the product, you can still submit an issue.

Second, search through issues already submitted by product (like the Elasticsearch issue list) to see whether a similar issues has been submitted to avoid duplicates. If you see an issue for your bug, you can choose to join the conversation or see if there’s a better opportunity for you to contribute.

If your bug hasn’t been flagged, then feel free to submit an issue for it in the Elastic product repository in which the bug occurs. For example, use the Kibana repository if the bug is Kibana related. Make sure to outline the nature of the bug, being as specific as possible — e.g. how it occurs, if you think it’s a query problem, etc. — and submit a test case that exhibits the issue. To make specificity easier, many of our projects have an issue template that outline the information we generally require. You can see an example of this in the Elasticsearch repository.

How should your test case look?

Use curl commands to make it easier for us to copy and paste into terminal. To create a test case in curl, you can export your curl commands using Kibana dev tools. Just reproduce the bug in the dev tool and export it to curl from there.

Using these dev tools, your test case will look something like this:

Suggesting a Feature Request

We love it when our community takes the time to let us know feature requests they’d like to see in updates of the Elastic Stack. In fact, many of the features you see in the stack today have come from suggestion by users like you.

If you have an idea for a feature, it’s easy to submit it to our team of engineers. Simply open up an issue in the Elastic repository for the product you’d like to see the feature (for example, the KIbana repository). Specify the use case for the suggested feature, outline the functionality you’d like to see (and why), and describe in deep detail exactly how the new feature will be used. Being specific helps us envision the feature and make it a reality. Regardless, we’ll reach out whether or not this is a feature we will pursue.

Submitting Code or Doc Changes

We also encourage our community to submit their own code and doc changes for problems they see in the stack. Just like submitting a bug fix, make sure to look through existing issues to see whether your concern is already being discussed. Feel free to join any existing discussions if you think you have something to contribute to the conversation, such as a fix that’s yet to be implemented.

But wait, there’s more!

Before you going out and write a ton of code, make sure to get the conversation rolling. We like to actively work with our contributors to refine their code and implement it. There’s lots of different ways to approach code and solve problems, and each project team will have their own preferences when handling code or doc changes. You can learn more about this process in our How We Handle Pull Requests blog post.

Submit Away

We hope this short tutorial has made the submission process a little less mysterious. If you have questions that aren’t answered here, make sure to check out the CONTRIBUTING.MD doc for your project and see if your query is answered there. Otherwise, the best way to learn is to get in there and submit issues. Read up, and start contributing.