To help the IT team – “Regulations for creating bugs” or “How to make a task clear to you from vacation”

Background

I wrote this regulation based on my experience as a lead in an IT company with a web application. The points from it have been tested in practice. The initial versions were (naturally) based on best practices from the Internet, agile and the experience of previous and current managers.

It is worth noting that although I was at some point in the role of a QA lead, I do not have the appropriate training, but I know many QA engineers and leads.

I personally recommend the following algorithm: copy-paste, adjustment to your specifics, practice of use. It is important to pay attention to the needs of developers, PMs, system analysts and other team members who will analyze bugs.

This regulation does not focus on any specific task tracking system. Use is possible both for JIRA, Kaiten, GitLab, Trello, and for an excel table.

general information

Key principles for creating a bug:

• imagine that the bug will be reviewed by a person who has virtually no connection with the software being developed (for example: a PM, a Scrum Master, a developer from another team, or you, after a vacation); The more detailed, clear and concise the bug is described, the better

• the bug may become irrelevant after some time – this is the norm, but you will still have to check it (perhaps in a year or two)

When creating a bug, you must specify the following points:

1. Name

2. A priority

3. Environment

4. Reproduction steps

5. Expected Result

6. Actual result

7. Additional Information

8. Connections

You can also optionally attach additional information to the bug in the form of screenshots (indicating the problem), videos, correspondence, links to other bugs/tasks, etc.

Bug items

Bug name

This paragraph should reflect the general problem of functionality in 3-5 words. The main criterion for a title is clarity for the reader.

At the beginning you can add conditional tags in square brackets (no more than 3), which can reflect the name of the feature, location of the bug, etc., understandable to most of the team.

If you cannot create a correct name for the bug in 5 words, then you can use conditional tags + a key phrase. In this case, there will be less clarity, but from this name the discussion participants will more easily understand what the conversation is about.

PS This is an extremely important point. The ability to correctly indicate the name is extremely valuable.

A priority

This is the importance of the bug for the product.

Several criteria are typically used to assess the priority of a bug:

1. Impact on Key Scenario

   • blocking (↑) or not blocking (↓)

   • visibility of the bug for the user (↑) or conditionally the bug is not visible (↓)

2. Playback frequency

   • overall probability of reproduction (higher chance – higher priority)

   • consistency of playback (fickle bugs ↓)

3. Other factors

   • importance for the customer

   • task due date

   • importance for the interacting department

   • and etc.

Conventionally, priorities can be:

1. Blocking (delivery of a feature or user scenario) – сделать срочно

2. Critical (visual bugs) – сделать в первую очередь

3. Medium priority – сделать во вторую очередь

4. Short – сделать когда будут свободны руки или никогда

Depending on the criteria, even a visual bug can be low priority, and refactoring (a change invisible to the user) can be critical. The priority may change over time. The primary assessment is made on a set of criteria and conditional priorities (see priority brackets).

Environment

This is a set of software (indicating versions) in which the bug is reproduced. This information reproduces and analyzes the bug.

Mandatory items are:

1. Frontend version

2. Backend version

3. Browser(s) + browser version

4. Stand (or git branch)

Reproduction steps

This is a user case – a scenario for reproducing the bug. This information is necessary to reproduce and analyze the bug. The more detailed the steps are, the better. It is allowed to use screenshots with marked signs.

Requirements for the item:

• steps are formed as an enumerable list

• steps are indicated from the key point (login/arrival to the site, etc.)

• the steps are indicated as accurately and in detail as possible; More information is better than less

PS If you want/need to use screenshots in steps, I recommend using footnotes and marking screenshots (example: in the text – “screen 2”, in the picture sign “2” at the top). This will greatly improve readability.

Expected Result (ER)

This is a result that should be observed in the system in a conditional norm.

Requirements:

• screenshot with the browser console open on the network tab

• screenshot with the browser console open on the console tab

• tabs should be scrolled down

If a design screen from figma is used for the OP, then the console is not required.

PS The network tab can be combined with the console tab (esc key in chromium with the network tab open).

Recommendations:

• indicate the result in one phrase or an unnumbered list

• provide a link to the source of truth (this could be a task, documentation, or a person)

Actual result (FR)

This is the actual result of the system after following these steps.

The recommendations and requirements are the same as in the OR.

Additional Information

This paragraph includes any information that may be useful to someone analyzing the bug. These can be links to feature tasks, screenshots, people, etc.

Separately, you can indicate your guesses about the type of bug. This can be extremely useful in the future when analyzing the backlog or fixing a bug.

Connections

These are links to tasks, problems, people, documentation, etc., noting the reason for creating the connection (if the functionality allows it).