Setting up Your Repository

Defect Management

How do you set up your Defect Repository?

If you've read the first blog on Defect Management, you will know that the first thing you will need to do is to ensure that your Defect Repository is set up in a manner that allows ease of entry, tracking and reporting of the defects. At a high level, this may seem easy, but there are many moving parts to a repository that we need to address.

You may be coming into an organization with an existing repository, or setting up one from scratch, but either way, you need to make sure that it is set up the way you need it for several areas of interest: defect entry, defect updates and defect reporting. Believe it or not, the latter, defect reporting, is the least important - for this blog, so we will address the other two for the most part, and catch reporting in a future blog.

1. Fields and Lists

First, you will need to review any default fields that come with your repository tool. There are usually the basics, such as Summary or Title, Description (detailed step by step to reproduce, and other information), Status or State, Severity, Date Opened/Closed, Detected By, Assigned To, and many more that you may or may not need. However, there are more basics you will want to make sure that, if they are not in the system, you create, such as these possibilities:

  • Priority
  • Defect Type
  • Defect Location (where in the application the defect occurred)
  • Reproducible
  • Closed Reason
  • Root cause
  • Cycle/release detected in
  • Environment encountered in
  • Business process, if tracked
  • Owner, either a resource or a department
  • Estimated Fix Time or Planned Resolution Date
  • Planned Release it will be in
  • If you are following an Agile approach, you may have the Epic and Feature
  • Tags or Keywords (for searchability)
  • … and any SPECIFICS for this project, for your company, etc., that you need to track or report on.

SO, now you have wracked your brain on fields you think you might need, it is time for you (if you haven't already) to talk to the business owners and other Sr. Management, asking THEM what they want to see, the data they want to capture, what reports and charts will be of interest and use for them. This may be department specific, for their department, or specific to the company, or simply a need that this particular department head has. I would suggest that you have a list of tables/charts ready for them so that you can give examples of metrics you can deliver, and what they would look like. This may guide them into selecting metrics that you know are valuable, and may also spark ideas in their heads on other metrics they might want to see.

NOW, you have a list of default, your own, and the rest of the business owners' required fields. Are they numbers? Strings? Memos (really big strings)? Lists? For each of these, you will want to make sure than they are configured correctly.

If this field is a number, should it be restricted? If it is a salary, it can't be less than zero. If it is a ranking value, it might be limited to between 1 and 10. If it is a quantity of an item, you might not want to allow decimals (1.7 years might be okay, but not 1.7 cars). For each numerical field, you will want to consider those restrictions.

If the field is a string, what is the maximum length of the string? The minimum length? For a city name, for instance, you might think that a minimum length of 4 is okay, but then you would be missing Rye, CO, Opp, AL and Eek, AK. In fact, internationally, you would be excluding Á, Norway, the name of 6 different villages there. So, best leave the minimum to 1 letter. And how about the maximum? Well, you might want to say, 25 characters, you will be able to cover "Chevy Chase Section Three" in Maryland, but you would miss out on "Village of Grosse Pointe Shores", in Michigan. So, push it to 31 characters, and you cover every town in the US. HOWEVER, internationally, you have "Llanfairpwllgwyngyllgogerychwyrndrobwllllantysiliogogogoch", in Wales, to worry about (as well as a lot of other places). Strings are generally 256 characters long, so in some cases, you should probably just use the default, unless there is a specific reason not to.

For instance, if it is a string like a telephone number or a Social Security Number or a ZIP code, you may want to do some masking, if your tool allows, and make sure that a US phone number always has a 3-3-4 format (312-555-1432), and a ZIP code has either a 5 or a 5-4 format, with the SSN always having a 3-2-4 format. Of course, internationally, these all change.

For lists, this is where you should put some focus. For each list, to be displayed as a drop-down list on your defect entry form, you need to make sure you have all of the available options, correctly spelled, and in alphabetical order (if the tool does not do that automatically). Be consistent. Don't capitalize some words and not others, for instance. Don't use "Deferred - December" for one, and "Deferred-June" for another (spaces around the dash), or "Def - May" (shortened "deferred"). Think about having to use these values in searches, and you need to (using the above example) separate out everything that starts with "Deferred".

2. Roles, Restrictions and Requirements

Now that you have all of the fields that you think you will need in order to fill out and report on defects, you will need to address each of them as follows:

  1. Who can SEE each field (is it visible on the form for them)
  2. Who can MODIFY each field (is it read-only on the form for them)
  3. Which fields MUST be filled in (required before saving the defect)
  4. Are there fields that should be hidden on defect creation, but visible afterwards for updates

The "Who" in the above questions, deals with the ROLE that the individual has. That might be Tester, Developer, Business Analyst, Project Manager, Admin, etc. Each member of the project will have a role like this. You need to think about if you want a Tester to set a Priority (usually a business function) or if there is a reason for them to see what the next release this defect is scheduled for. Should a developer be able to close out a defect, or only the tester who is tasked with testing it after the fix? Should the initial opening of the defect be able to be saved if there is not Summary/Title, or no Severity, or no indication of the location in the application the defect was found, or in what environment the test was being run in? Should the date it was detected or closed be able to be modified by anyone who is NOT the system? Should you be able to Close a defect that was just entered without a comment as to why it was moved directly from New to Closed, without any intermediate steps? These and many other questions need to be considered not only by you and the users and business owners and Sr. Management, but possibly by the Audit department. What rules and regulations might they need to have in place for the process to pass audit at the end of the project?

3. Laying out the Defect Import Form

As important as understanding the needs of the users regarding each of the necessary fields is the layout of the form that will be used to enter the defect, and to review it thereafter. Although you can reduce the initial form for a new defect to the required fields only, I would advise against it, as other non-required information may well be known by the tester entering the defect and you would lose that information. Likewise, I would not display a different layout of fields for each role. If some fields should not be seen by everyone, tuck them in at the bottom where making them not visible to some users will not change the remaining upper portion of the form. One of the key reasons for this is that, during triage meetings, or while two people with different roles review the defect together, if the layout of the fields on the form is very different, effort is expended (and frustration increased) with one of the users trying to find the field that they knew to be one location, and now it is over in a totally different. If everyone is used to seeing the exact same screen, that confusion is removed.

As for the layout in general, be logical, and group things. Highest priority, most used fields at the top. Date Created and Created By should be right next to each other. Detected in Cycle, Release and Environment should probably be grouped. If you have sets of things (User Field 1, User Field 2 … User Field 6), group them all under each other, in order in one column, for instance.

Note that this might take some trial and error, but you it can be mostly accomplished before going live with the Defect Entry form by running through a Triage Meeting in your head and following the flow of the make-believe discussion. Or by playing the part of the tester entering the defect, and seeing if the layout of the form is conducive to the flow of entry of the defect information.

So, there it is - Setting up your Defect Repository in a nutshell. Understand what data you and all other entities in the organization need to gather, what that data needs to look like, who needs to see that data (or not see it), edit it or not, and what is required or not, and then make sure that the entry and review of the data is clean and intuitive to use. That's it for this blog. The next one will combine two steps, and look at training users and then verifying that they are entering the defect correctly into the repository.