Start by establishing whether it is a system bug at all
Not every message on the screen is a failure. Exceptions describing invalid input, such as no access, a missing page or a malformed request, are excluded from reporting as non-failures. If the operator sees a message about missing permissions, first check the user's role, and only then report a bug.
It is also worth distinguishing three situations: a bug visible to a single user, a repeatable bug affecting many people, and a bug in a safety alarm. The third situation has the highest priority. Work safety alarms are not silenced: if an alarm did not arrive or rang incorrectly, report it at once and give the time, so the vendor can find the event in the log.
How to describe the bug step by step
The report should be written so that a person who did not see your screen can repeat the bug. Such a description consists of several fixed elements.
- System version: the release hash shown in the system. In error reports the release version is the short hash of the deployed image commit, the same as the image tag in the registry, so the bug can be linked to a specific change.
- Who and when: the user's role and the exact time of the event, ideally with the hour.
- What the user wanted to do: one sentence on the goal, for example issuing a work permit.
- Steps: a numbered list of clicks from the login screen to the moment of the error.
- Expected and observed result: two short sentences.
- Evidence: a screenshot showing the message and, if possible, the time from the device clock.
Why numbered steps matter more than a general description
The browser E2E tests replicate the user step by step: login, the admin panel, work planning, permits, reports, documentation, maps and analytics. The vendor turns a good description of steps into a test, so a report with steps has a chance to enter the regression package and not come back after the next update.
Report priority by situation
What the vendor sees on its own and what you do not need to describe
All instances report uncaught exceptions to one error monitoring project. This means that a serious server error is usually seen by the vendor on its own, even before anyone reports it. A user report is still needed, because it adds context: what the operator was doing and what effect they saw.
Automated browser tests fail when an uncaught JavaScript exception or a server error appears. For this reason such errors are caught first by the automated checks, while a human report is most useful for problems that do not throw an exception: a wrong result, a missing entry or a misleading screen.
If the same bug repeats for many people or in several places of the system, state this in the report: repeatability and the number of people help the vendor judge the priority and scope of the problem. The way the vendor groups bugs in one monitoring tool is described in a separate case study.
Audit evidence and tracking the report
For the information security department, the audit trail matters: who reported, when, which version they gave and when they received an answer. It is worth keeping a register of reports on the plant side, with the vendor's report number, version, date and status.
When the vendor confirms the bug, check in its reply whether it names the version in which the fix will be released. This lets you later verify that the bug disappeared after the update, for example by repeating the steps from the report. Details of acceptance after an update are described in the checklist for accepting system updates.
Video
Frequently asked questions
Do I need to report a bug if the vendor has monitoring?
Yes, if the bug does not throw an exception. Monitoring sees uncaught exceptions, but it does not see a wrong result, a missing entry or a misleading screen.
Where do I get the system version for a report?
The release version is the short hash of the deployed image commit. Ask the plant administrator or the vendor where it is shown in your installation.
Is a no-access message a failure?
Usually not. Access errors are excluded from reporting as non-failures, so first check the user's permissions.
Agree on the reporting process
We will show a report template and the handling path in your plant. Book a conversation with InnerWeb.
Let's talk