Bug Report Template for GitLab

This document outlines a comprehensive bug report template designed for use in GitLab repositories. It breaks down the essential sections to include in a bug report, ensuring clarity and completeness for effective issue tracking and resolution.

1. Create an issue for ech section below in your GitLab repository. For example: "Technical Steps for Creating the Template in GitLab"
2. Copy the checklist items from each section into the corresponding issues' descriptions.
3. Start working on implementing the bug report template in your repository. Check off each step as you complete it.

Bug Reports Usually Done by Users

While this template is designed for maintainers to set up, remember that bug reports are typically submitted by users or testers. Ensure the template is user-friendly and easy to understand.

Technical Steps for Creating the Template in GitLab

Put learning into action by making the real issue template.

- [ ] Create the folder `.gitlab/issue_templates/` in your repository (https://docs.gitlab.com/user/project/description_templates/)
- [ ] Add a new file named `bug_report.md`
- [ ] Put a quick action into the `bug_report.md` file to set a distinguishing label, e.g. `/label ~"bug report"` (https://docs.gitlab.com/user/project/quick_actions/)
- [ ] Commit and push to your main branch
- [ ] Test by opening a new issue and selecting “Bug Report” as the template
- [ ] Refine using the checklist items in each section below

Summary & Context

Start by naming the issue clearly and giving the reader a quick overview.

- [ ] Include a placeholder for a **specific, descriptive title** (e.g. “Login button unresponsive on Firefox”) `/title <new title>` action (https://docs.gitlab.com/user/project/quick_actions/)
- [ ] Add a short **description field** asking: “What is happening and where?”
- [ ] Provide an optional **‘Related feature or issue’** line in the template

Environment

Describe where the bug occurs so others can reproduce it.

- [ ] Add a section titled **Environment**
- [ ] Include lines for **OS / Browser / Device**
- [ ] Include a field for **App version or Git branch**
- [ ] Include an optional line for **Configuration or test data**

Preconditions / Setup

State what conditions were true before the issue happened.

- [ ] Add a **Preconditions** section
- [ ] Write a guiding sentence: “Describe the setup before reproducing the issue”
- [ ] Include an example: “User logged in as admin and data file X was loaded”

Steps to Reproduce

Explain how to make the bug happen again — step by step.

- [ ] Add a section titled **Steps to Reproduce**
- [ ] Insert a numbered example list:
      1. Go to the login page  
      2. Enter valid credentials  
      3. Click **Login**
- [ ] Add an instruction: “List exact steps so anyone can repeat the issue”

Expected vs. Actual Behavior

Show the difference between what should happen and what did happen.

- [ ] Add two headings: **Expected Behavior** and **Actual Behavior**
- [ ] Under Expected, write: “Describe what you expected to happen”
- [ ] Under Actual, write: “Describe what actually happened, including any error messages”

Attachments / Evidence

Provide proof of the problem for faster understanding and debugging.

- [ ] Add a section titled **Attachments**
- [ ] Include a line: “Attach screenshots, logs, or screen recordings here”
- [ ] Add a reminder: “Remove or anonymize sensitive data”

Impact / Severity

Communicate how serious the problem is — but let maintainers verify later.

- [ ] Include a short prompt: “How severe is this issue?”
- [ ] Add suggested choices: *minor / major / blocker*
- [ ] Include an example: “Blocks user from completing checkout process”

Possible Cause / Notes

(Optional) Suggest what might be causing the issue or where to look.

- [ ] Add a section titled **Possible Cause (optional)**
- [ ] Include a prompt: “If you suspect a cause, describe it here”
- [ ] Add a placeholder for related commit or issue links

Verification / Test

Think ahead to how the team will confirm the bug is fixed.

- [ ] Add a section titled **Verification**
- [ ] Include a prompt: “Describe how to test after the fix”
- [ ] Provide an example: “Repeat the steps above and confirm login succeeds without delay”

Status & Responsibility

Acknowledge what not to include in the template (project-managed fields).

- [ ] Add a reminder: “Assignee, cost and price estimations, and milestones are set by maintainers after triage”
- [ ] Do not include these as fields in the template