Issue Tracker User Guide

[Fred]

Hello Everyone!

This thread is part of a series on fostering a culture of quality control through excellent process. In general, the issue tracker seems to be not well understood at all. As such, it's clearly time for a guide, and this is it! :-)

Upon thinking about that, it's clear why:

• Most people have never heard of them, let alone used them.
• Those who have heard about them and not used them have no idea either.
• Those who have used them a little bit probably didn't do it properly without mentoring, and have now forgotten anyway.
• Those that use them extensively probably use them in one of the thousand other work flow patterns that are possible, not the way I want you to here.

The following posts will cover:

• Reporting An Issue (for everyone)
• Handling A Reported Issue (for devs)
• Fixing An Issue For A Reporter
• Testing And Closing Issues
• Work Flow Summary
• Quirks Of Our Issue Tracker
• Important Links On Our Tracker

The Basics

A simple run down on the main points of issue trackers.

What's The Point?

Software is complicated, issue trackers can help software developers keep track of all the issues that invariably come up during the application development process. They also keep peoples problems with a software system from being forgotten or hidden and help organise work on a software project and keep the process manageable.

What's In It For Me?

Traceability and transparency on system problems. There is always a history of what happened, why, who worked on it, who reported it, etc. Your problems won't get forgotten or left unexplained, you'll be "in the loop" with what happens, no matter what it is. Lastly, it helps guarantee that you do get fixes for your issues, and in a more timely fashion!

I Have A Problem! What To Do?

Tell us! :-) If you're 100% sure that you have found a problem, it's OK to go straight to the issue tracker. If you're not, it's probably best to mention it on the forum in the user support section first or drop into one of the IRC channels for a quick chat. If you go straight to the tracker you may wish to post a discussion thread in the user support section with a link to your report on the issue tracker.

If you have any feedback on this guide, or anything to ask, please go here!

Fred.

[Fred]

Reporting An Issue (for everyone)

So, you've come across some issue while using the FreeEMS system? It doesn't have some feature that you desperately need and can not live without? It has some dangerous flaw that is going to melt your pistons? You thought of a way of making it even MORE awesome than it already is, and want to share that? You found a flaw in the documentation and want to formally share it to ensure it gets fixed promptly? You came across a minor niggle and want to note it such that it's not forgotten or swept under the carpet? This is the post for you! :-)

Note: Your issue can be with ANY part of the system, firmware, PC applications, web stuff, documentation, etc, all of it.

You'll need an account to submit an issue report, so if you don't have one, sign up now! Your status will be "reporter" by default, if you need more power than that, for example because you're a developer, let me know and if I agree I'll fix it ASAP :-)

Follow these straight forward steps:

Note: All projects have different fields and categories etc, if something in the below steps is not visible, it's not part of a report for the project that you're reporting an issue to.

1. Head over to: http://issues.freeems.org
2. Project: In the top right corner, select the project (If it's not there, complain here!)
3. Category: Choose the most suitable one. (If you need a new category, choose something else and tell us!)
4. Reproducibility: For features choose "N/A", for docs choose "always" and for bugs just be honest.
5. Severity: For features choose "feature", for anything else, just be honest.
6. Priority: If it's important to you, let us know here. If it's not important to you, choose "low", otherwise leave it as "normal".
7. Profile: For features choose "All All All", for bugs choose your platform or ask for it to be added, for firmware choose your hardware platform.
8. Product Version: If a release, select it, if a dev version, choose the latest SNAPSHOT version.
9. Assign To: Unless you're a developer, leave this field alone, it will be automatically correct, or highlighted brightly if not assigned.
10. Target Version: Unless you're a developer, leave this field blank, a developer will assign a suitable target version once it has been reviewed.
11. Summary: A short sentence that adequately describes the issue. Not too long, not vague.
12. Description: This is the meat in the sandwich and where you should fully describe what you observed, how you would like to see it work, what functionality a suitable fix can be measured by, etc.
13. Steps To Reproduce: If this isn't covered adequately in the description, or is a long sequence of things to do, tell others how to expose the flaw here.
14. Additional Information: If you are using a development version, include your git hash here, along with any customisations, or attach a file with changed code and a commit that it can be diffed against. If you marked priority as anything other than normal, justify it here. If you think a new category or project or platform variant is required, put it here. Put anything else that doesn't fit in above here too.
15. Issue Type: Tell us whether it's a feature request, bug, improvement, task, etc.
16. Risk Of Breakage: Leave this for a developer to determine.
17. Upload File: If you have a screen shot or code or anything else, choose it here and it will be uploaded when you submit.
18. Sit back and relax: While you wait for emails letting you know what's happening!

It's not the end of the world if the above selections are not perfect, however please note that the better they are, the less developer time is spent fixing them, and that means more development time and a better system, which is good for _everyone_ :-) Also, don't be offended if/when developers change some of the details, they probably have good reasons for it and probably know better. If you strongly disagree, leave a note on the issue to that effect with justifications.

Fred.

[Fred]

Handling A Reported Issue

When an issue gets reported, a developer has to review it and handle it in some way. This process flows in the following way:

• The first step is to simply read through it and make sure that it makes sense and has sufficient information
• If there is sufficient information the developer should acknowledge the issue in the tracker
• If there is not enough information the developer will tell the reporter what they need to do and assign it back to them
• Once acknowledged the developer should then investigate the issue and attempt to reproduce and/or confirm it
• If it can be reproduced and/or confirmed then it should be marked as confirmed in the tracker and work begins
• If it can't be reproduced and/or confirmed the developer will tell the reporter what they need to do and assign it back to them

Please refer to the diagram below for a visual representation of this flow. Note, it is possible that after some work, the developer needs to involve the reporter in order to check certain details or try out partial fixes, in these cases the issue will be assigned back to the reporter with suitable instructions. Sometimes it is useful for the developer to be able speak to or chat with the reporter, in cases where this is done, a summary of the conversation and the outcome should be recorded in the tracker.

Developers should not be impatient or rude with reporters and should assume that they have done their best, which is usually the case if they've gone to the trouble to report it formally in the first place. Requests for more information should be polite and friendly. Making the process unpleasant for the reporter simply means that they will stop filing issues on your software and you'll stop having the opportunity to fix them, and that's bad for everyone involved.

[Fred]

Fixing An Issue For A Reporter

Once an issue is confirmed, work should begin, at the indicated or scheduled time. If you need more information from the reporter during this process, indicate that to them through some appropriate means, usually by assigning the issue back to them with a comment telling them what you need. However, if it's minor, a chat in IRC might be sufficient. If things go smoothly and you're able to fix the issue, and thoroughly test that your fix is good and breaks nothing else that is related, it's time to let the world know.

There are two things that you need to do:

1. Include "Fixes #123" somewhere in your descriptive commit comment
2. Change the status to "resolved" and specify the resolution and other details

The latter is done as follows:

First, select "resolved" from the menu to the right of the "Change Status To" button, then click the button:



Second, when the new screen, as shown below, comes up, select:

• The "Resolution", usually "fixed", but whatever is appropriate.
• Who it should be "Assigned To" for checking/closing, usually the reporter, never yourself.
• The "Fixed In Version", almost always the next scheduled release version.

Don't forget to include the git hash in which the issue is fixed in the comment. Usually "Fixed in commit 7afee87676e876faf768ed987" or similar, and anything else that needs to be said, too.

If you mess up doing this and forget to select one of the pieces of information, use the edit button to change whatever is wrong. Doing this maintains the status as resolved whereas, for example, reassigning it to the reporter using the "assign to" changes the status to "assigned" (on the basis that they should now handle it, which implies everything that you've already done).

If you didn't mess up, it should look something like this:



At that point it's up to the reporter to test and close the issue if they are satisfied with it, or reopen send it back to you if they are not. Note, it's generally not OK to close the issue yourself unless A you reported it and B it's minor. If you didn't report it, it's not appropriate to close it. If it's major it should be peer reviewed and assigned to some other developer to confirm the fix and close. If it's both major and not reported by you, you may wish to pass it through another developer before assigning it back to the reporter. This is an excellent practice.

[Fred]

Testing And Closing Issues

Once a developer thinks he has fixed your issue, or even just told you how to avoid the mistake that it turned out you were making, he will mark it "resolved-fixed" and assign the issue back to you. At this point the ball is in the reporters court, once again, and it is now up to them to test the software involved and prove whether or not the developer really did fix the problem.

The comment that the developer left on the issue when marking it resolved-fixed should have told you which version contains the fix for your issue. Obtain that version through your usual mechanism and give it a try. Be sure to not only test the specific thing that you complained about in the first place, but also related aspects of the program as it is possible that the "fix" broke something else. This is usually only a significant issue in poorly designed software, though, so it's relatively unlikely to happen here!

If you're satisfied with the new behaviour of the application in question, go into the issue on the tracker and find the "Change Status To" button which is below the main description and attached files sections. To the right of it it will say "new" in a drop down, change that to "closed" and click the button.



In the screen that comes up enter a comment letting future readers know that the fix was tested and confirmed by you, the original reporter.



Your comment should read something like "Closing this issue, tested and confirmed fixed in 7887a87f879a87d7899". If you didn't screw up it should now look something like this:



If the problem is still present in the latest version, firstly double check that you really have the latest version through whatever means are appropriate for the specific application. Once you've confirmed both that the version is correct and that your issue is still present in it, you need to reopen the issue. To do this. click the re-open button in the lower right of this image:



And explain what you did to prove that in the comment area. Before clicking submit please change the "Assigned To" option to refer to the developer who you have been dealing with. The screen will look like this:



From there the cycle repeats and it's back in their hands!

In a company that I used to work for we used a system called JIRA and referred to this process as "JIRA tennis" as it resembles the game with the passing backward and forwards that occur between developer and end user :-)

[Fred]

Work Flow Summary

This diagram shows the usual flow of events for the issue tracker. Note a "problem" could be a missing feature, a bug, an improvement, bad docs, or whatever. Also note that "Fixed" could mean that there wasn't a problem in the first place, that a feature was added, that something was explained, etc, IE, just that the user's problem is solved, code change is not necessarily implied. Additionally "Works For Me" could mean "Won't Fix" or a variety of other resolutions.





I hope that this diagram makes the flow of actions clear enough for anyone to use the system! :-)

Attached is the source for the diagram. If you think you can make it more clear, be my guest!

IssueTrackerWorkflow.zip

(527 Bytes) Downloaded 1847 times

[Fred]

Quirks Of Our Issue Tracker

Our tracker, MantisBT, has some minor oddities and for the good of all I'm going to list them here as I think of them.

Project Handling

Right now, the only one that I can think of is the way it handles multiple projects! In the top right you can see which project you're currently viewing. This affects everything that you do. If you're on OpenLogViewer, you can not see any firmware, loader, mtx or whatever else stuff unless explicitly linked to it. This can be confusing at times. If you report an issue, it automatically goes to the one you're viewing. If you're viewing "All Projects' then you have to choose a project before you can proceed to the rest of the report.

Session Timeouts

With current settings your session gets garbage collected after 4 hours of inactivity. Thus if you happen to leave a window with an issue open for longer than that, please reload it before commenting on it or filling out a report or anything involving you typing. If you don't, when you hit submit, you're saying goodbye to your work. The back button does not allow you to retrieve what you had typed in, and there is no forward button as there is when the same thing happens on this forum. If you put a lot of effort into your comment, as I regularly do, this can be infuriating. Firefox users may find the following plugin helpful:

Profile Fill In Button

Clicking this clears all of the fields, with no way to get your data back. Preston got burned by this and made an issue here, enjoy the laugh: http://issues.freeems.org/view.php?id=708

https://addons.mozilla.org/en-US/firefo ... -recovery/

[Fred]

Important Links On Our Tracker

• FreeEMS Issue Tracker
• Firmware Roadmap
• EMStudio Roadmap
• OpenLogViewer Roadmap
• Loader Roadmap

Use the first link for reporting all issues, but be sure to check which project view you're using and set it appropriately first.

Fred.

[Fred]

Again, if after reading the above, you still don't understand something and want to ask a question, the comments thread is here:

viewtopic.php?f=41&t=1382

Feel free to offer feedback on the format of this thread, the content of the posts in it, or ask questions about using the tracker in the preferred way.

Fred.

[Fred]

Bump for screen shots now included for the three less obvious steps!