There will be times when you discover a bug in OH. This tutorial explains how to file an issue so the developers can know about the bug and hopefully fix it.
Do I Have a Bug?
openHAB is a complex system with lots of options and ways to configure various capabilities. As the old saying goes, openHAB gives you a lot of rope with which to hang yourself.
So how do I as an average user know whether I’ve done something wrong or if there is a bug? The good news is we don’t expect you.
Step 1: Ask for Help
If you are having a problem, please open a new topic here on the forum. Try to pick the category that makes the most sense to you but don’t worry if you get it wrong. We can move it if we need to. But choosing the right category increases the likelihood that the right people will see and help.
There are a group of forum users who scan pretty much every new posting. These users are usually not developers but long time users of OH, or newer users who are looking to contribute back to the community. These users will ask lots of questions and have you try experiments to help narrow down the source of the problem.
But, there are lots of posts and very few of these tier one helpers. So please review How to ask a good question / Help Us Help You. Respect the time these users are donating by providing as much detail as possible.
Step 2: You Have a Bug
The tier one folks have determined you have a bug. If they have they will ask you to please file an issue.
Why do I have to file the issue? Well, you are the one with the problem. The tier one folks are not experiencing the same problem as you; they may not even be using the same binding or similar setting. Often the developers will need more information from you than has already been provided in order to reproduce the problem and hopefully solve it. Thus the user(s) who are actually experiencing the problem must be the ones to file the issue.
Filing an Issue
Step 3: Where to File an Issue
All of the openHAB repositories are hosted on Github under https://github.com/openhab. There are lots of repositories there and it’s not always obvious which one is the correct one. Luckily, the tier one folks from above will tell you the proper repository to file the issue in. Usually we will provide a link but if we don’t browse through the list until you find the repo mentioned.
Step 4: Create an Account
To file an issue you must create a GitHub account. An account is free and easy to set up. You can have an account in just a couple minutes.
Step 5: Search for Similar Issues
There may already be an issue opened for this problem. The tier one folks often are not able to follow all the issues as they get created so may not be aware if an issue already exists. If you find a similar issue, please add a comment indicating you have the same issue and provide a link to the forum thread and any additional details you think might be relevant.
Step 6: Create an Issue
If you didn’t find an issue that seems to apply, create a new issue.
The text entry for the new issue will come pre-filled with text asking for all the information needed in the issue. Please provide all the requested information. Also provide a link to the forum thread.
Once created, return to the original thread and post a link to the Issue you just created. Others who are experiencing the same problem will be able to follow the Issue as it get’s worked and contribute other information that might be critical to solving the problem.
Step 7: Help Solve the Problem
The developers will likely need additional information to diagnose and solve the source of the problem. Please answer any questions asked and provide any artifacts requested.
Now What?
Hopefully a developer will start working and help solve the problem. However, sometimes the developer may be offline for extended periods. Sometimes there isn’t a developer willing to work on the issue. Sometimes there are higher priorities among the developers.
We cannot promise that the issue you discovered will get fixed nor how quickly it will be fixed. Some get fixed within hours of being reported. Others have been open for years. Please be patient and understanding. Like the tier one folks, all of the developers are also donating their time to this project.
I Can Fix It Myself!
Fantastic! If you are talking about code then you probably already know how to manage submitting a PR so this section will focus on updates to the docs which anyone can do.
Even if you plan on filing it yourself, it is good form to open an issue to let others there is a problem. Let them know in the issue that you intend to file a PR to address it.
For simple fixes, making the update couldn’t be easier. At the bottom of each documentation page there is a link that will take you straight to the file on GitHub.
Click the edit icon.
This will create a fork of the project under your user name. Make your changes right there in the browser. At the bottom, create a title for your changes and describe your changes and why you made them. Make the last line in this comment "Signed off by " showing that you are agreeing to apply the openHAB open source license to your contributions. Then click “Propose file change”. Also add “Solves issue #XYZ” where XYZ is the issue number you created. This will automatically link this PR to that issue.
This will open a diff view showing you what you changed. If you are satisfied, click “Create pull request”.
This will submit the proposed changes to the original github repo for review before it’s merged into the baseline. There may be comments and proposed changes you need to make before it get’s approved.
Congratulations and thanks!
If you happen to have more than one issue that you want to work on, you will want to create branches, but that’s beyond the scope of this tutorial. Search and you will find GitHub has lots of great tutorials covering this.