Document our bug reporting requirements and create an issue template which meets them.

[jmcook1186]

Sub of #651

What

Update the contribution guidelines in our main repository and docs website to help users report bugs effectively and Update the Github template for bug reports across IF repositories

Why

As a core developer I want to be able to diagnose, assess and fix bugs as quickly as possible.
As a user/community developer I want a clear way to report bugs to the core team so that they can be dealt with as quickly as possible.
As a core dev I want our users to submit bug reports in a standard format so we can triage it effectively and apply our decision making process consistently
As a user, I want a clear explanation of what's expected when I report a bug so I can be confident it will be handled effectively.

Context

We can make our bug response much more efficient and effective by clearly communicating to users what information we need to reproduce, diagnose and fix bugs. If users conform to our standard, we will be able to handle them in our triage calls without requiring lots of back and forth async discussion with the user. We are updating our bug report template in a separate ticket and this issue adds explicit guidance on how to fill out the template to our contribution documentation in the IF repository and our docs website to make sure users can provide us the information we need to address their issues efficiently and effectively.

Part of the QA epic. An updated bug report template will help users and developers provide all the information we need to triage, reproduce and fix bugs.

We should make it so a bug report contains all the information required to reproduce a bug and to make it as easy as possible to fix. This includes:

• a description of the error
• a description of the expected behaviour
• a description of the actual behaviour
• steps to reproduce
• the manifest file that generated the error
• runtime information such as OS, node version, package.json, IF version

Statement of Work

• Change if contributions documentation to point to if/contributing.md (handled in Remove contributions page if-docs#69)
• Write up the guidance for bug reporting in the if/contributions.md (Handled in Add bug triage docs #663)
• Create/update the issue template for bug reporting in all if repos to align with our guidance. (handled iun Update bug report template #654)

This ticket covers any async discussions or calls required to confirm the information required on the bug reporting template, creating a PR to update the template on each of the IF repositories (if, if-plugins, if-unofficial-plugins, if-plugin-template).

Acceptance criteria

• Guidance created that includes: (Handled in Add bug triage docs #663)

• What criteria does a bug need for us to accept it (It must be reproducible and all the information and materials provided for us to reproduce the error)

• Our rubric for triaging bugs into high, medium and low.

• Our SLAs and actions for bugs that are high, medium or low.

• Template created that includes

• a description of the error

• a description of the expected behaviour

• a description of the actual behaviour

• steps to reproduce (the exact CLI commands that were run)

EITHER

• the manifest file that generated the error

• links to any code (e.g. your own plugin code), it must be available online.

• runtime information such as OS, node version, package.json, IF version
  OR

• A version of stackblitz which replicates the bug

• All if-* repos have a bug report matching the above template
  (handled in Update issue templates in if-plugins if-plugins#84
  Update issue templates in if-unofficial-plugins if-unofficial-plugins#80
  Update issue template in if-plugin-template if-plugin-template#7)

Deadline
tbc

Reviewer

[jawache]

@jmcook1186 see my note on #590, let's merge it makes more sense to work in these hand in hand, the guidance should be created first in my opinion as one informs the other, we might write the guidance and realize through that the template needs updating and vice versa.

FYI: I'm assuming anything that involves a PR has had team approval implicitly.

[MariamKhalatova]

@jawache @jmcook1186 Proposing a new bug report template, which you can see and review on bug-report-template branch in IF repository. Will appreciate your feedbacks and comments.
Our previous issue template contained just text without separated blocks, which made reporting difficult (you have to remove old text or comment, add current context).
The new version is more readable, as you can see logically separated blocks with helpful placeholders, btw you can also upload manifest to each block.
Looks like this

[jawache]

Thanks @MariamKhalatova, can you link the PR itself?

[MariamKhalatova]

@jawache Yes, here it is
#644

[zanete]

@jmcook1186 I wanted to clarify a couple of things to see what needs to happen to move this one along:

• the scope of this issue - are all the checkboxes under Statement of Work as well as the Acceptance Criteria part of the scope? If so, should we refine it so that it is under one list?
• Are all things on @MariamKhalatova plate or is this a shared issue (which means that perhaps it wasn't wise for me to close the Refine bug reporting guidance documentation #590

[jmcook1186]

There is a PR open for the bug reporting template itself (#654) but it needs approving and then replicating across the other IF repositories.
There are also tickets assigned to me for providing the bug assessment rubric and labelling across the IF repos (#589, #588).

Then I wanted to describe the bug triage process and reporting guidelines into the contribution guidelines in our docs and if readme.

Actually makes most sense to assign this to me.

@zanete

[jawache]

@jmcook1186 for me the priority is the bug triage process (agreement for what's high, med, low) I can see you've done the majority of work there and from where I sit it looks like we just need to make a call. Happy for you to make it and others can weigh in if they don't agree (but it's been in that doc for a while so there has been plenty of opportunities for others to give their opinions).

The template and reporting requirements would be defined by our triage requirements, e.g. if to triage high we need to understand X, X needs to be something people add to a bug report etc.. so I think the triage is the main one and everything else will follow naturally on from that.

[jmcook1186]

Re-opening as not all acceptance criteria are met. Only the bug template is merged so far - and it also needs replicating across the other IF repositories.

@MariamKhalatova could you raise PRs to if-plugins, if-unofficial-plugins and if-plugin-template with an identical template, please?

I am writing documentation for bug reporting requirements now.

[jmcook1186]

Update:

Documentation added to IF readme and CONTRIBUTING.md here: #663
Documentation added to if.greensoftware.foundation here: Green-Software-Foundation/if-docs#68

[MariamKhalatova]

Bug reporting templates were updated in if, if-plugins, if-unofficial-plugins, if-plugin-template repositories
Corresponding PRs are the following:
#654
Green-Software-Foundation/if-plugins#84
Green-Software-Foundation/if-unofficial-plugins#80
Green-Software-Foundation/if-plugin-template#7

[zanete]

@MariamKhalatova please review and then we can merge and close this 💪

[MariamKhalatova]

@jmcook1186 I reviewed these PRs , left some comments. Please check
#663
Green-Software-Foundation/if-docs#68