Triaging (working with) bugs
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 Launchpad (or log in using openID), where the Widelands bug tracker is.
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.
Tips, tricks and useful links
As mentioned above, you can find the bug tracker here. This page will great you with a selection of open bugs, ordered by the most important 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 take a look at all bugs not marked Fix Released, sorted the most recently changed ones. 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.
On the right side of the list of bugs, there are links to show specific selections of bugs, where new bugs may be one of the more interesting ones. Below the various selections, the official bug tags are displayed. These will each link to all bugs marked with that particular tag. See further down for descriptions of the different tags.
Launchpad allows projects to set milestones with specific goals. This means bugs can be targeted to a specific milestone. This allows people to see which bugs and blueprints are targeted for the next release, or later. For instance, build19-rc1 contains a list of what is scheduled for the release of build19.
This is perhaps one of the most important element about bugs; the current status. Different bugs will have different statuses, and they can be changed when information is added, or a fix is created. The descriptions of the various statuses is based on comment #3 here, but has been slightly elaborated in some places.
- New: All bugs reported will initially have this status. This means these bugs may not even have been looked at by someone other than the reporter!)
- Incomplete: These reports are missing information or discussion before it can be categorized. If no information is provided, the bug will eventually expire.
- Expired: When an Incomplete bug report does not receive any new comments or other changes for some time (60 days), it will be closed as expired. (Note: you cannot actually change the bug status to Expired manually, this only happens automatically.)
- Opinion: The bug is considered closed, but discussion may continue. In the past this was used to mark issues which had an ongoing discussion, but due to the intended use bugs with this status did not show up in the list of open bugs.
- Invalid: Doesn't belong to Widelands.
- Won't fixed: Won't fixed for some reason
- Confirmed: The bug can be reproduced (by someone other than the person who reported the issue). No idea how to solve this yet.
- Triaged: A comment should be added that describes were or how this can be fixed. Work on the bug can start immediately.
- In progress: Someone is working on this or the fix is committed in another branch then trunk. (These bugs should also be assigned to the person or team working on it)
- Fix committed: Fix is in trunk (development version of Widelands)
- Fix released: Fix is in a released build or build candidate. A note should be added that states the package that contains the fix. All bugs fixed in build 16 or earlier have this status.
When a bug is reported, the status defaults to new. Currently, this means only the reporter is known to experience this problem. It is not sure what is causing it nor if others are affected by it. A bug is considered confirmed if more than one person is experiencing the same problem. To confirm a bug, 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:
Start the game.
Click the button marked "New game"
The game crashed.
All you need to do is follow the instructions, and see if you have the same result. If you do, you can mark the bug as confirmed. You can do this by clicking the yellow exclamation mark next to the current status and select "Confirmed" from the list. 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.
Bugs with little information
Sometimes it can be hard to understand exactly what the bug report is about or how to trigger it. 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, change the status of the bug report to Incomplete to signal it needs more information. If the reporter provides the information, either see if you can reproduce the bug (and set status to confirmed), or revert it back to new to signal the information have been provided and the report can be looked at.
When asking questions, please subscribe to the bug report 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!'."
Tags are a nice way to mark bug reports which covers the same area. This makes it possible to collect all the bugs affecting one area, for instance the editor, so that it gets easier to find these bugs 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 bug as a duplicate of an older one.
Widelands has some official tags which should be used, and some unoffical ones in addition. You can see the current tags for a bug report just beneath the bug description (above the first comment). To add a new comment, click on the yellow exclamation mark and type in the tag you want to add. If you want to add more than one, add a space between them, for instance "crash editor" which will make it available for people searching for crash and editor, while "crasheditor" would only be found by people searching for that exact phrase.
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.
Official Widelands bug tags
atlanteans - affects the Atlantean tribe, buildings or workers
balancing - deals with balance issue, issues which may give one tribe an advantage over the others
barbarians - affects the Barbarian tribe, buildings or workers
buildsystem - related to the compilation and build process of Widelands
campaign - affects one of the campaing maps
cmake - issues related to building Widelands with cmake. See also buildsystem
computerplayer - problems with the computerplayer, anything affecting the AI players.
crash - this bug makes Widelands crash. Anything that triggers a crash should be marked with this.
economy - dealing with the economy and wares
editor - any issues related to the map editor
empire - affects the Empire tribe, buildings or workers
gamedata - various things related to the content of the game, such as conf-files.
gameplay - issues related to the mechanics and how the game is played. A quick (slightly bad) example of the difference is that a farm is a building which employs a farmer, produces wheat and use this image is gamedata, while how the farm affects playing the game (providing food to workers) is considered gameplay.
graphic - anything visual such as workers, buildings, immovables
internationalization - anything to to with internationalization or translations, for instance bad translations in a specific language or parts of the text which is not translatable.
lua - anything related to lua scripts/scripting
military - issues with soldiers, combat or anything military-related
multiplayer - bugs which occured or are only triggered when playing multiplayer
network - related to network
savegame - anything dealing with saving and loading games OR bugs where a savegame have been attached to demonstrate a bug
scons - issues related to building Widelands with scons. See also buildsystem. (Is this even supported anymore?)
statistics - anything related to statistics, like general statistics and productivity
ui - short for User Interface, covers anything the user interacts with such as buttons and menus
windows - from the currently tagged bug this seems to cover windows in the game, not the operating system (?)
worker - anything that deal with either a specific worker or all workers in general
Unofficial bug tags
These will not show up in the list of official bug tags, but may be used on rare occasions
arch - Marks all bugs which occurs on Arch Linux, which is a rolling release distro, meaning it usually has the latest version of programs and libraries. Any issues discovered here may be due to changes in newer version which most likely will need to be dealt with sooner or later.
haiku - Haiku is an open source remake of the operating system BeOS, currently in development. Covers all bugs which occurs in Widelands on this platform
regression - a regression is term which describes when something that used to work has stopped working. This can be either functionality which is no longer working due to changes, or fixed bugs which resurfaces.
Importance tells developers which bugs should be fixed as soon as possible, which can wait a while, and which are suggestions that can be added sooner or later. This helps them prioritize what should be worked on to fix the most severe issues. (Though being an open source project, everyone is of course free to work on what they want). Triagers can help developers by marking importance according to how severe the bug is and how many players it will affect. Note that only members of the Widelands development team can change importance.
- Undecided: The default importance, to indicate it has not yet been decided nor set.
- Critical: Issues that will impact or affect most of, if not all users. Things that makes Widelands unplayable, such as not starting at all or crashing when you attempt to start a new game on any map.
- High: Things that will affect a large number of users, or have great impact on the users affected.
- Medium: More important issues than Low, though only some players will probably not encounter the issue. Anything than crashes Widelands should be assigned at least Medium importance.
- Low: Bugs in rarely used features which will not affect the majority of players, minor annoyances, typos and similar issues. Also includes bugs with an easy workaround.
- Wishlist: Does not cover issues present in Widelands today, but adjustments or additions which could improve the game (feature requests).
(The Ubuntu BugSquad also has some guidelines for deciding on importance, though not all points are relevant for Widelands.)
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. 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?
This section is partially inspired by some of the documentation by the Ubuntu BugSquad. Since Ubuntu is using Launchpad as well, a lot of what their documentation may be relevant for Widelands bug triaging as well. However, keep in mind that there may be some Ubuntu-specific things which may not apply to Widelands. That said, they have a really awesome triage guide and knowledge base