A Guide To Writing Good Bug Reports and Job Requests

Summary

The ECS programmers will try to help you with any problems you have regarding ECS computing facilities. But our job can be made much easier if you follow the guidelines given here.

Before requesting help from us you should at least read the first two sections of this technical note, which provide a brief overview of the RT (Request Tracker) system used by ECS and some advice on how to make good requests.

The remaining sections of the technical note describe RT in more detail. Some tips that apply specifically to that system are given. It is not essential that you read these sections before requesting help although doing so may avoid issues that occasionally crop up.

Details

The most important thing to know is that requests for assistance shouldn't be emailed to a particular technical support staff member. Instead they should be sent to either bugs@ecs.vuw.ac.nz (for problem reports) or jobs@ecs.vuw.ac.nz (for general queries or requests for software installation, changing file access permissions, user account issues, etc). It doesn't matter if you use the wrong address though, as the same people see emails to both!

Creating an RT Request

Sending a request to either of these addresses creates a "ticket" in our RT system which the entire technical support team will see. Any further email correspondence relating to that request will include the ticket number that RT has assigned to it in the subject line (eg: '[ECS #XXXXXX]'). This allows RT to keep all correspondence related to a particular issue together.

If you have multiple unrelated issues you should send them as separate RT requests. That makes it easier for different members of the technical support team to deal with the different issues.

It is preferable that requests to RT are NOT also Cc'd to other recipients as explained below.

Lastly, new requests NOT be sent to a ticket created by an earlier request (ie: make sure that the subject line of your new request doesn't include an existing ticket number). In particular don't make your new request by replying to an email related to a previous ticket. The reasons for this are explained in more detail below. But briefly, if your new request doesn't create a new ticket it will probably only be seen by the technical support team member who dealt with the previous request. And that may have an impact on how quickly your new request gets dealt with.

More detailed information on RT is provided later.

Writing a Good Bug Report or Job Request

In order to help solve your problems or deal with your requests quickly we need a good bug report or well specified request. If we have to contact you for more information it will take longer to help you.

A good bug report has these things:

1. A descriptive subject line
2. Steps to reproduce the problem. If we can't replicate it we can't fix it.
3. What you expected to see. Don't assume we know how to use the program you are having problems with.
4. What you saw instead. We can't read your mind!
5. What computer you were using when the problem occurred.
6. If you are sending your request from an email address other than your ECS/SMS or MyVUW one, what your ECS/SMS login name and/or student ID is. If we can't identify you it may be much harder to help you.

The computer name may or may not be relevant but telling us what it is allows us to determine that. If you aren't sure of the name tell us the room number and (for rooms containing more than one computer) where in the room it is (ie: "3rd from left in the 2nd row").

What makes a good job request is harder to categorise. In general, providing more detail is better than less, but too much may make it hard for us to determine exactly what you want us to do. As an example of the level of detail required, if you want some software installed you should tell us: where we can get it; what version you want; what OS you expect to run it on; and any licencing restrictions or costs that you are aware of.

Below are some additional tips that apply to both problem reports and job requests.

It can be useful if you tell us why you need a problem solved or some work done. We may be able to suggest a work-around or an alternative approach. For example, if you describe what you will be doing with some software you want installed we may be able to tell you how to achieve the same result with software already on our systems.

If your request involves a web site, tell us the actual URL rather than assuming we know where it is or will be able to find it based on a less precise description. So instead of just saying "I tried to login to google and ..." you could say "I tried to login to google at https://accounts.google.com/ServiceLogin and ...".

You should also give us some idea how urgent your request is so it can be dealt with appropriately (though keep in mind that "A lack of planning on your part does not constitute an emergency on mine"!). If you have a deadline let us know in your initial request rather than a later follow up ("I asked for this a week ago but forgot to say I needed it by tomorrow..."). Please be honest when providing this information. Saying something is urgent simply to get it dealt with sooner is not very polite to others who may have genuinely urgent requests.

Finally, if you send your request from a non-ECS email address make sure you tell us your ECS username and/or student ID. This is most important for problems that don't affect all users. Knowing who you are may also make a difference to when, how or even if we can help you. Unfortunately we can't deal with all requests immediately so staff and graduate students may get priority over undergraduates for problems affecting only one person. On the other hand a problem that affects all students in a large undergraduate class would get higher priority.

A bad example:

From: anonymous_guy@gmail.com
Subject: Help

I tried to see the Google in Firefox, but it didn't work. I need this now.

In the above is "it" Firefox or the google web page? What was "it" supposed to do? Do you really need this now? And who is anonymous_guy@gmail.com?

A good example:

From: anonymous_guy@gmail.com
Subject: Firefox doesn't display google search page properly on ECS Linux Computers

I visited http://www.google.com in Firefox on the machine imlay.ecs.vuw.ac.nz in CO232. When I visit the page from my home computer running windows I am presented with an option to search for web pages; there are two buttons below the text input box. However, I am unable to see either of these buttons on the ECS computer. This prevents me from running a search, which I need to prepare a presentation for later today.

My ECS login name is kingstlind.

The ECS RT (Request Tracker) System

As described above, requests should be made via RT by emailing either bugs@ecs.vuw.ac.nz or jobs@ecs.vuw.ac.nz. Alternatively you can use the RT self service web interface (although this only works if you have previously submitted at least one request by email which ensures that you are correctly set up in our RT system).

Reasons For Using RT

The reasons we prefer requests be made via RT include:

1. All team members get to see your request and the one who can best (most knowledgeable, least busy, etc) deal with it will do so.
2. We can tell if someone is already working on a request and so avoid duplication of effort.
3. It helps team members keep track of what they are working on and to prioritise their work.
4. Team members can see what each other is working on and may be able to offer assistance or advice.
5. Your request won't get forgotten about or lost in one team member's overflowing inbox or be delayed if a team member is away.
6. If a team member is unable to continue working on a request it's much easier for someone else to take over and to see all the previous correspondence.

This doesn't mean that you can't talk to us in person though. Some reasons for doing so are:

• Queries that can be dealt with quickly are sometimes best handled that way. But please don't be offended if we can't help you right away and we ask you to submit the request via RT.
• If you are intending to submit an RT request it may be a good idea to talk to someone first to ensure that what you are asking for is feasible and/or to determine what information should be included in the request.
• If you have already submitted an RT request, once you know who is working on it it may be easier to talk to them in person rather than communicating solely by email.

More About RT ("The Gory Details")

When a new request is received by RT it will be assigned a "ticket number" and entered into a request database. A copy of it will also be emailed to all members of the ECS technical support team and a "ticket receipt" emailed back to the submitter. In those emails the tag "[ECS #XXXXX]" (where XXXXX is the ticket number) will have been added to the start of the original subject line. Appropriate email headers are also added to (try to) ensure that any follow up emails will be sent back to RT.

Any support team member can take ownership of a ticket, which means that they rather than the whole team receive follow up emails. But team members who don't own a ticket can still see correspondence relating to that ticket in the database and can also make their own contributions. And any team member can add themselves (or any other person) to a ticket as a "watcher" so they receive follow up emails like the owner and original submitter.

Tips For Interacting With RT by Email

Here are some things to keep in mind when using email (rather than the self service interface) to interact with RT.

Leave the "[ECS #XXXXX]" tag unaltered in the subject line of any follow up email:

This allows RT to associate the follow up with the right ticket in its database so that all related correspondence can be found easily. It also means that RT can email copies of the follow up to the correct ticket's watchers.

For RT to do this the tag must be left exactly as it was (including the '[' and ']' characters and the "ECS #" prefix).

If the tag is omitted a new ticket will be created in the database and the whole ECS technical support team will be notified. This can result in confusion, especially if the original ticket is now owned (and being dealt with) by one team member.

If the tag is altered the follow up may end up associated with the wrong ticket (and therefore be emailed to the wrong watchers) or be rejected by RT.

Use your mail program's "reply to sender" function to send follow up email:

Replying to an existing ticket message when writing a follow up guarantees that the RT tag in the subject will be correct (as long as you don't edit it!). It also ensures the follow up will be sent back to RT due to headers that RT adds to all email it sends out.

Using "reply to sender" is preferable to "reply to all" since the latter may result in watchers receiving multiple copies of the follow up - one directly from your email program and one sent by RT.

Avoid emailing a new request to RT and also to other recipients:

We prefer that you don't do this due to the confusion it can cause.

RT will automatically add the other recipients as 'Cc' watchers of the new ticket. This means they will receive two copies of your email - one generated by RT and one directly from you. When they reply one of the following will occur:

1. If they "reply to sender" to the copy sent by RT the "right thing" happens.
2. If they "reply to sender" to the copy sent directly RT will not see their reply. So potentially useful information will not get recorded in the ticket or be seen by the ticket watchers (including the ticket owner or members of the technical support team).
3. If they "reply to all" to the copy sent by RT, depending on the email headers some of the recipients will receive two copies. The copy sent directly (not via RT) will not have appropriate headers so the previous case may then occur for replies to the reply.
4. If they "reply to all" to the copy sent directly RT will receive the message, but as there won't be an "[ECS #XXXXX]" tag in the subject, it will create a new ticket. Then we end up with two tickets in our database, each containing some of the correspondence related to the issue. And all the recipients again get two copies of the message. It's even worse if the request was Cc'd to multiple people or to a mailing list and multiple recipients reply in this way.

In some cases you may feel that others should know about a request you are making. If so, rather than sending an email consider creating the ticket using the RT self service interface. Then all the people you Cc the request to only get one copy of your message and the subject and other email headers will be set to ensure that follow up correspondence is correctly processed by RT.

Avoid adding new cc's when following up to an existing ticket.

RT only adds cc'ed addresses as ticket watchers on initial ticket creation. So if you cc a follow up to a new person, unless we notice and manually add them as a ticket watcher, they may not see all subsequent correspondence. If you must do this mention it in the text of your follow up so we can add them as watchers if appropriate.

Try to keep one problem report or job request per ticket:

The different requests may not be dealt with by the same person. Having them in a single ticket makes them harder for us to manage.

Think carefully before re-opening an old ticket that has been closed (resolved):

Once a problem has been fixed or a job completed we will "close" (resolve) the ticket. The correspondence remains in the database so we can search for it if we need to, but the closed ticket won't appear in our list of tickets currently needing attention.

An email received by RT with the tag ('[ECS #XXXXX]') of a closed ticket will result in that ticket being re-opened and the new email added to it. The email will also be redistributed to the ticket's "watchers" (the technical support staff and others with an interest in that issue). Often this will only be the one member of the technical support team who took "ownership" of and dealt with the ticket. For this reason you should never re-open a closed ticket if you are making a new request that is unrelated to that in the closed ticket.

But even for a new request that is (somewhat) related you should still think carefully about whether to reopen the previous ticket or create a new one. The reasons for this are outlined in the following paragraphs.

Tech support team members take ownership of tickets so that the rest of the team don't see emails relating to issues that they are not dealing with. So when you follow up to an old ticket all the team members won't see your email, perhaps including the person best able to help. Also, if only one team member receives your email and they are away on leave or busy with other work your new request may not get dealt with as quickly as you would like.

Even if a closed ticket concerns something done for you previously that you now want repeated, its probably best to create a new ticket. That's because the staff member who did the work for you last time may not be the best person to do it this time (even if they are they are the one who has 'always' done it before). The entire team should see your repeated request so we are better able to share our workload.

If a ticket was closed because an issue was thought to be resolved when it actually wasn't (or it was resolved but reoccurs), reopening it is OK soon enough after it was closed. Then the person who worked on the ticket previously will most likely be the best one to work on it again. But if too much time has elapsed before you reopen the ticket that may not be the case. Also, what appears to you to be a repeat of a previous issue may have a different cause (especially if the previous occurrence was a while ago) and so the same person may not be the best. There's no hard rule for how long a ticket can be closed and it be OK to reopen it, but a rough guideline might be a couple of weeks.

In general if there is any doubt about whether to re-open a closed ticket, don't - create a new ticket instead! If possible provide a reference to the old ticket (tell us its ticket number or if you don't know it, any details that will help us find it in the database). We can review what actions were taken the last time and if we think a new ticket shouldn't have been created we will re-open the original and merge the new one in to it.

Don't include large attachments in requests:

Requests remain in the RT database forever and we don't need/want it clogged up with large attachments. A better alternative would be to leave a copy of the attachment(s) in a folder on one of our servers and tell us the location. If we believe it would be better for a copy of the attachment to be permanently stored in our database we can attach it ourselves. Note: using screenshots to illustrate a problem is OK as they are usually quite small. However they do have the disadvantage that we can't search for text in them so cutting and pasting the text of an error message is preferable if possible.

Stop and think about what you are adding into the RT discussion; before pressing Send:

Along similar lines to the consideration of placing large attachments into the RT system, is a consideration of what you, often just one participant in a discussion with the Technical Staff, are placing back into the RT system in the body of your emails.

Try to remember (or even visit the SelfService interface to see) that RT keeps a copy of the full body of all the email correspondence, which means that if you simply reply to an email without trimming the content, the RT system is now storing everything twice, and then, if another correspondent replies to your reply, the RT system is now storing everything three times.

Many email clients no longer bother to show you the old message content that you, unknowingly, will be sending back, so try and check, and in most cases, simply delete any old content. In some cases, say where you've been asked a number of questions, then trim the old content as much as possible and insert your answer after each question.

Similarly, just because your email client acts like a colouring book, remember that not everyone reading your email will have chosen to use the same client as you, so don't refer to coloured sections of your email, indeed, it's probably better not to use colour at all.