Latest Posts

Changes in TriagingBugs

Editor Comment

Reworked for new process on GitHub


Revision Differences of Revision 21

#Triaging (working with) issues ¶

This section will describe how to triage bugs, or in other words help out with bug reports. In a nutshell, it's the process of checking if a reported bug is reproducible (i.e. following a set of instructions will always demonstrate the issue), adding extra information, changing status or adding tags etc. The purpose of triaging bugs is to help the developers and make it easier for them to fix the problem. All you need to get started is to register on [GitHub](https://github.com/) (or log in using openID), where the [Widelands bug tracker](https://github.com/widelands/widelands/issues) is. ¶

[TOC] ¶

###Note ¶
Please note that this can be considered work in progress, so more information may be added, edited or split out if it makes sense to create a new page. ¶


##How you can help ¶

To contribute with bug triaging, there are some fairly easy things you can do. This will mostly consist of confirming or improving bug reports. For some options you need to be a member of the Widelands development team, but most actions are available to anyone. ¶

The goal is to make sure bug reports are understandable and contain enough information for a developer to start working on it. While it in some cases it will be the same person who triage and fix the bug, however how to fix bugs is beyond the scope of this article. ¶

##Selecting an issue to work on ¶

For finding issues that need triage, go to the [Issue triage](https://github.com/widelands/widelands/projects/2) project and pick an issue from the "To Do" or "In Progress" columns. We have set up this project in such a way that newly reported issues are added to it automatically (hopefully, we still need to confirm that this is working). Pull the issue over to the **In Progress** column. ¶

As mentioned above, you can find the bug tracker [here](https://github.com/widelands/widelands/issues). This page will great you with a selection of open bugs, ordered by the newest ones first. ¶

While this is interesting, for day to day work on bugs, it may be more useful to stay up to date on which issues have recently been commented or changed in other ways. One way of doing this is to change the sort order to [Recently updated](https://github.com/widelands/widelands/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc). If someones comments or in other ways changes a bug report, you will be able to see something has changed as soon as you refresh the page. (This can of course been done instead or in addition to subscribing to all bug mail. ¶

Not that issues can have labels. Once you become familiar with the Widelands struture, setting labels is already a great help. ¶

GitHub allows projects to set [milestones](https://github.com/widelands/widelands/milestones) with specific goals. This means bugs can be targeted to a specific milestone. This allows people to see issues targeted for the next release, or later. ¶

In addition to Milestones, GitHub also allows to create project boards. We have set one up for [issue triage](https://github.com/widelands/widelands/projects/2). ¶


##Categorizing an issue ¶
After you have selected an issue, decide whether it's a bug, an enhancement/feature request or a cleanup/refacoring task, and add the appropriate label. If you know Widelands well enough, you can also add further appropriate labels. ¶

If Widelands crashes or hangs, assign the issue to the current milestone too. ¶


##Confirming bugs ¶

When a bug is reported, it will come without any labels. At this time, only the reporter is known to experience this problem. It is not sure what is causing it nor if others are affected by it. An issue is considered confirmed if more than one person is experiencing the same problem. To confirm an issue, read through the description of the bug and see if you can reproduce the problem. Most good bug reports leaves instructions for how to trigger the problem. For instance: ¶

1. Start the game. ¶

2. Click the button marked "New game" ¶

3. The game crashed. ¶

All you need to do is follow the instructions, and see if you have the same result. If you do, you pull the issue over to the **Done** column. As always when you change status, you should leave a message stating why you changed it. In this case, something like "By following your instructions, the game crashed here as well." should be sufficient. You can also add additional information such as which operating system you are running, in case the crash is limited to certain platforms or post error messages if you saw any.issue tracker](https://github.com/widelands/widelands/issues) is. ¶

[TOC] ¶

##How you can help ¶

The goal of triaging issues is to make sure bug reports are understandable and contain enough information for a developer to start working on them. There are some fairly easy things you can do to help which are described in the sections below. ¶

If you have any ideas on improving the triage process, please post on the forum or open a new issue on GitHub. You are also welcome to edit this wiki article. ¶

**Note:** If there is an option for which you need to be a member of the Widelands development team and GitHub is blocking you, please let us know your GitHub nickname and we'll add you to the team. ¶

**Note:** Automatically adding new issues to the Triage project isn't working yet. So, we need to check for new issues regularly on the main page of the [issue tracker](https://github.com/widelands/widelands/issues). You can also watch the repostory if you want to get e-mail notifications about any changes. ¶


## Familiarize yourself with the labels ¶

If you have never worked on Widelands issues before, please have a look at our list of [labels](https://github.com/widelands/widelands/labels) and their descriptions. ¶

Labels are a nice way to mark issues which cover the same area. This makes it possible to collect all the issues affecting one area, for instance the editor, so that it gets easier to find these issues later on. This can be a developer who wants to work on the editor and want to know what needs to be done, when you want to reference an older bug in discussion because it deals with the same issue, or if you want to mark a new issue as a duplicate of an older one. ¶

You can see the current labels for an issue on the right-hand side when looking at the issue. Click the little gear icon to add/remove labels. ¶


##Select an issue to work on ¶

For finding issues that need triage, go to the [Issue triage](https://github.com/widelands/widelands/projects/2) project and pick an issue from the **To Do** column. Alternatively, you can also follow-up on an issue in a different column. ¶


##Categorize the issue ¶
* Pull the issue over to the **In Progress** column ¶
* Read the description carefully ¶
* Search all [issues](https://github.com/widelands/widelands/issues) for relevant keywords to find any duplicates. If it's a duplicate: ¶
* Add the [duplicate](https://github.com/widelands/widelands/labels/duplicate) label to the issue ¶
* Add a comment with a link to the other issue ¶
* Close the issue. This will automatically shift it to the **Done** column and the triage is complete. ¶
* If it's not a duplicate: ¶
* Add all [labels](https://github.com/widelands/widelands/labels) that fit. Decide whether it's a bug, an enhancement/feature request or a cleanup/refactoring or a documentation task etc, and add the appropriate label for this too. ¶
* If Widelands crashes or hangs or if it's an annoying bug, assign the issue to the current milestone too to ensure that it will not fall off the radar. ¶
* You can shift the issue back to the **To Do** column if you don't want to do any more work on it. ¶

##If it's a feature/enhancement request/documentation issue: ¶
* If the request is clear and you agree, pull it over to the **Done** column. ¶
* If it still needs discussion/consensus, pull it over to the **Under Discussion** column. Add a comment as you see fit. ¶

##If it's a bug or a crash ¶

Check for bugs that need confirming in the **To Do** and **Needs Information** columns. Pick an issue, read through the description and see if you can reproduce the problem. Most good bug reports leave instructions for how to trigger the problem. For instance: ¶

1. Start the game. ¶

2. Click the button marked "New game" ¶

3. The game crashed. ¶

All you need to do is follow the instructions, and see if you have the same result. ¶

* If you can reproduce it: ¶
1. Ensure that the reproduction steps are explained clearly ¶
2. Add a comment that it has been reproduced, including the Widelands version and your operating system. Something like "Reproduced on Windows 10 with Widelands git-1234." should be sufficient ¶
3. If you saw any error messages, add them to your comment ¶
4. Pull the issue over to the **Done** column ¶
* If you can't reproduce it: ¶
1. Add a comment to request more information ¶
2. Pull the issue over to the **Needs Information** column ¶


##Bugs and enhancement/feature requests with little information ¶

Sometimes it can be hard to understand exactly what the bug report is about or how to trigger it, or a feature request still needs to be fleshed out and agreed upon. Imagine the following bug report: ¶

> The game crashed. ¶

Ok, so the game crashed. This gives us very little information what is happening, and more importantly why it happens. For a developer to fix this and stop the game from crashing he or she needs to know as much as possible about how the crash is triggered in order to reproduce it and fix the underlying issue. In case of bug reports lacking information, we need to ask the reporter to provide more information. Remember to be polite in your requests and thank reporters when they provide additional information. In the example above, there are some basic things we probably would like to know to check if we can provoke the same crash (and mark the bug confirmed). Relevant information would be: ¶

* which version of Widelands the reporter is running. Older versions may have bugs which are already fixed in later versions. When checking bugs reported in older versions, please check against the latest stable version or the development version if the issue is still present. ¶

* which operating system the reporter is using. Due to differences between Windows, Mac Os X, Linux and various, less-known operating systems, there may be issues which only occur on some platforms. However the majority of bugs will most likely affect all platforms, so if you can reproduce a bug on a different operating system it can be confirmed. On the other hand, bugs you cannot reproduce on a different platform than the reporters should be checked by someone running the same system to see if there is something only affecting. In the latter case, please leave a message informing that the bug is not affecting you operating system. ¶
o ¶
* ask the reporter to include error messages if any. If the game crashes, or you are unable to load a map it will most likely display an error message stating what went wrong. Even though they may not make much sense, a developer may recognize what the problem is. Even in a worst case scenario, the developer will be able to search for the error message in the source code to see where the problem occured. ¶

When asking follow up questions such as these, keep the status bug report in the "**In Progress** column to signal it needs more information. If the reporter provides the information, either see if you can reproduce the bug (and move it to the **Done** column), or move it back to the **To Do** column to signal the information have been provided and the report can be looked at. ¶

When asking questions, please subscribe to the issue in question so that you will be notified when more information is posted. ¶

-- ¶

Alternatively, you can also provide the missing information yourself. If a bug report contains a good description of the bug but for instance is lacking an error message or a screenshot of what happens, you can collect this and add it in a comment. For instance: ¶

> Hello, the game crashes when I click on that button as well. I get an error message saying 'Command not found. Not a valid button!'. ¶

##Labels ¶

Labels are a nice way to mark issues which cover the same area. This makes it possible to collect all the issues affecting one area, for instance the editor, so that it gets easier to find these issues later on. This can be a developer who wants to work on the editor and want to know what needs to be done, when you want to reference an older bug in discussion because it deals with the same issue, or if you want to mark a new issue as a duplicate of an older one. ¶

You can see the current labels for an issue on the right-hand side when looking at the issue. Click the little gear iceon to add/remove labels. ¶

Below are a list of the official tags and a short description for each. Most of the tags are straight-forward and easy to understand. (Though some are not to they point where they are slightly confusing. If you can fill out some of the empty descriptions, please do) Note that there may be some overlap between the different tags, and more than one may be relevant for a particular report. ¶


## Questions or other feedback ¶

If something is unclear, or you would like learn more about a certain aspect of bug triaging, feel free to leave questions or suggestions here or in the [forum thread](http://wl.widelands.org/forum/topic/802/). No questions are considered silly. Remember, there is probably others with the same questions or may be someone looking for it in the future. Example: ¶

* How do I do X? ¶

* Could someone write a section on Y? ¶

###Questions: ¶
-