The Bug Tracker (BT), the Features Request Tracker (FT), and the Patch Tracker (PT) are the official tools to communicate bugs, feature requests, and proposed changes to the developers. While bug reports, feature requests, and patches are always welcome over any channel, these are the only tools that make sure they will not be forgotten / hidden in the past archives. All users are encourage to make use of these tools. In the following text I explain the basic usage and set some policies with regard to Hugin.
Moreover, discussion of tracker tickets is welcome on the Mailing List (ML). This includes (non-exhaustive list):
- requests to test bugs and patches
- requests for opinions on ways to fix bugs and implement new features
- enlarging the base of interested user / tester to encompass a variety of platforms
- insuring follow up on anonymous tickets
Structure of a Ticket
Whether it is to report a bug or to work on it, familiarizing with the structure of a ticket in the tracker is the first step. Look at existing tickets for examples.
- On top is the summary, the ID, and the last update information. With "Tech & Admin" permission the summary is editable.
- Under the details header is the initial comment, followed by some information about the status of the ticket. The status information is editable with "Tech & Admin" permission.
- Most important, at least initially, is who submitted the ticket. A ticket can be submitted anonymously but it is strongly recommended that users register with SourceForge (it's free and SF has a consistent track record of respectful committment to user's privacy) and log in before creating a ticket or commenting on one. If you have OpenID there is no need to remember another password.
- Next is the comments thread. It may be condensed - click on the + icon on the right to expand it. When working on a ticket it is important to be aware that the "Details" section may not be everything there is to read. The follow ups often contain relevant / critical information. All users can add to the discussion.
- The attached files section lists all files that have been uploaded. This is usually meant for logs and patches. Project files (.pto) and screenshots still fit the weight limits. For full test cases with images this is not practicable - better store them somewhere on the web and publish a link in a comment. If you need such web space, ask on the ML.
- Users with "Tech & Admin" permission can associate a ticket to another one, marking it as a duplicate.
- Last but not least, all changes are listed.
Initial Bug Report
All users are encouraged to report bugs. Please help us improve the quality of the bug reports and the information available to the developers by following these guidelines:
We need to know as much as possible about your system. Which version? What processor? How much memory? How much disk space is available, particularly temporary space? Are all updates recommended by the system's distributor applied? Have you customized the system? added/replaced libraries?
If you have access to a second system, please validate the bug before reporting it.
We also need to know as much as possible about the software used. Which version of Hugin? Where did you install it from? Did you compile Hugin yourself? An easy way to identify your version of Hugin is to look up the About Hugin dialog (Menu Help -> About Hugin) and report the whole version string.
Hugin depends on third party libraries and tools such as libpano and enblend/enfuse. Unless you have downloaded a Windows installer or a Mac bundle (that are self-contained), we'd need to know the same information for the dependencies. Where and when did you install them from?
Often times the nature of your project, particularly the images, will help understand the bug. How many images? What format? Do they have EXIF data? What camera make/model? Is it HDR? Often time, providing the .pto file (can be attached in the BT) is a valuable input to the analysis process. If you have access to web-space, providing the full test case including images (in JPG format and/or resized to reduce storage/bandwidth need) can also help.
What are the steps that need to be undertaken to reproduce the bug? Does it happen consistently all the times, or only sporadically? what is the expected application behavior and how does it differ from the observed application behavior?
To triage bugs a user need a SourceForge login and "Tech & Admin" permission to the BT. Permission will be liberally given to users who have shown continued, relevant contributions to the debugging process.
- Log on to the [https://sourceforge.net/tracker/?limit=20&sort=open_date&sortdir=desc&offset=0&group_id=77506&atid=550441&status=1
BT] (the link is already filtered for opened ticket sorted from the most recent one on top).
- Start with the oldest bug that has not been triaged yet. Ideally the new reports are identified by Priority 5, although at the time of writing many old reports still have Priority 5. It is also possible to be alerted to new reports by subscribing the tracker mailing list.
- Read the ticket and make sure you fully understand it. When in doubt, leave it for more experienced users to triage or ask on the ML.
- If you determine that the ticket is a duplicate, mark it as such and close it.
- There are frequently appearing error messages such as "precondition violation", "false --compression", "Mask is entirely black but white image was not identified as redundant", etc... that need entries in the hugin FAQ - Duplicates should be closed with a link to the FAQ.
- Assign Category, Group, Priority according to the policies in the next sections.
- Add clarifying questions to the bug ticket if applicable. In doing so, compare the currently available information against the requested information listed above in "Reporting a Bug" and the specifics of the report.
- If the ticket was entered anonymously, determine the likelyhood that the developers may need additional feedback. Ask for that feedback on the ML. Eventually set the report to pending status so that if nobody acts on the request it will be closed in two weeks for lack of information.
- When in doubt, ask on the ML.
Every user can validate a bug against their system / software and add a comment to validate the bug. We encourage all users to do so. The more validation information we have, the better. We need to narrow down whether a bug applies to a specific operating system or across the board. And it is also very useful to know if a bug applies to a specific context or if it applies also in different contexts.
- To validate a specific bug, simply try to reproduce it by following the instructions described in the ticket.
- Add a comment to the ticket reporting your observation.
- Were you able to reproduce the bug?
- It is important to add context to your validation: what operating system? what version of Hugin?
Bug Fixing and Testing
Everybody is encouraged to provide fixes and patches to correct bugs. Only developers can add them to the repository. Write access to the repository will be liverally given to users who need it.
- when a developer fixed a bug, he can ask the ML for testing.
- a fix tested on the developers system only can be set to Pending status.
- when at least one user validates a fix on a different system and there are no reports that the fix does not work, the bug report can be closed.
- The more complete a bug report, the more attention it is likely to get.
- Anonymous bug reports are set on Pending status by default, unless the report is complete enough not to need further feedback and/or there is interest from contributors to work on the report.
- When triaging a bug, set it's priority to something different than 5 so that priority 5 reports are known to be untriaged.
We use categories to indicate if the bug is platform specific, although some tickets still carry "legacy categories" that are unrelated to the platforms.
We use groups to indicate which tool is affected by the bug.
We use priorities to sort out the the tickets.
- 9: show stopper for the current release
- more than 5: bug affects a large number of use cases.
- 5: new bug that needs to be triaged
- less than 5: bug affects a small number of use cases - rare / specific situation
The tracker enables the assignement of a bug to a person. It is considered rude to assign a bug to somebody else without their prior consent. Developers sometimes assign a bug to themselves to signal they are working on it, but we do not use this feature too often.