How to report a bug

Receiving feedback is one of the most important parts of software development.

At Nextbit, we track issues using Gitlab - not only bugs, but also feature requests and brainstorming.

Writing a good bug report (or feature request) requires some time (around 15 minutes), but more time is spent upfront, less time is spent lately by the team trying to reproduce a bug.

Reporting a bug

When you report a bug, follow this simple scheme:

  • Describe what you did (I clicked a, b and then c)

  • Describe what you expected (I expected a button labelled d)

  • Describe what happened (A button labelled e appeared)

Try to be specific, and make reproducing the bug easy. Try to add more details possible, and avoid using generic did not work.

If possible, attach a screenshot of the screen, highlighting what was broken.

Add details of your environment (OS and browser).

If the project you’re reporting a bug against is composed by multiple sub-projects, and you don’t know which sub-projects are affected, just choose one. Developers will move it to the right sub-project in a second moment.

If you think your bug is urgent, notify someone on Teams.

Asking a new feature

When you ask for a new feature, try to include these points in your proposal:

  • Which problem you are trying to solve with this feature

  • Possible benefits

  • A user case as example

Triaging an issue

When you, as developer of the project, triage an issue, try to fill these fields:

  • assignee(s): who will fix this issue?

  • milestone: when we need to fix this issue?

  • severity: add the label with the severity (~critical, ~high, ~medium, ~low)

  • try to estimate how much time will be needed

Working with big issues

Sometimes an issue requires multiple steps to be completed, or it is too big to be fixed with just one merge request. In such cases, it is better to create sub issues to be linked as steps in the main issue. In this way you have a fast overview of everything that is needed to do, and still can assign and work on single issues.

You can use the markdown checkbock ([]) to keep track of what has been done from the main issue itself, where you will keep general discussions on the problem.

This issue is a good example of such a decomposition.