From 00579e23bef7d50427c3a2b259b64c11958e2f6e Mon Sep 17 00:00:00 2001 From: jmc <33655003+jmcook1186@users.noreply.github.com> Date: Wed, 24 Apr 2024 14:57:18 +0100 Subject: [PATCH 1/7] feat(package): add bug reporting guidance to processes doc --- CONTRIBUTING.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 13b12ed80..79c75d35f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,6 +10,7 @@ The following document is a rule set of guidelines for contributing. ## Table of Contents - [What and when to contribute](#what-and-when-to-contribute) +- [Reporting bugs](#reporting-bugs) - [Code Contributions](#code-contributions) - [Step 1: Fork](#step-1-fork) - [Step 2: Branch](#step-2-branch) @@ -27,6 +28,59 @@ The following document is a rule set of guidelines for contributing. You can contribute anything to the IF, but we are likely to close out unsolicited PRs without merging them. Our issue board is completely open and we have tags (`help-wanted`, `good-first-issue`) to help contributors to choose tasks to work on. We recommend speaking to the core team on Github before starting working on an issue. You can do this by raising an issue or commenting on an existing issue. This helps us to direct your energy is directions that are aligned with our roadmap, prevent multiple people working on the same task, and better manage our board. This all makes it much more likely that your work will get merged. +## Reporting bugs + +We appreciate bug reports! If you experience an issue with IF or one of our plugins, you can report it using our bug reporting template. To do this: + +1. Go to the [IF repository](https://github.com/Green-Software-Foundation/if) (or [plugin repository](https://github.com/Green-Software-Foundation/if) if you bug relates to a specific plugin) +2. Click on the `Issues` tab +3. Click on `Create New Issue` and select the `Bug Report` template. +4. Fill out the requested information. + +The more detailed information you provide int hen bug report, the easier it will be for us to diagnose, triage and resolve your issue. We ask for some simple information about your issue, including a description of the error, the expected behaviour, the actual behaviour and the stepos we cna take to reproduce the error in our local environments. We also then prompt you to provide a link to [Stackblitz]() or a similar online environemnt where we can run your mnaifest and observe the error. If you prefer *not* to send a link, we would appreciate the a copy of the manifest file that you ran to produce the error, information about your runtime environment and any additional code that's required to reproduce. This is all designed to enable us to reproduce the same error and debug it for you. + +Once a suitably detailed bug report exists, we will triage it. Triage means that the core team will assign an urgency label to your bug report - either Low, Medium or High. The assessment rubric is as follows: + +| | Consequence | Severity | +| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------- | +| Bugs in IF core | unusable framework, incorrect calculations | 5 | +| Bugs in if-plugins | core pathways fail, IF very limited in functionality | 5 | +| Bugs in if-unofficial | Third party plugins harder to use, limits IF to standard lib | 3 | +| Bugs in template | Harder to build plugins, ecosystem growth is impacted | 2 | +| Bugs in docs | product does not match expectation, hard to debug, frustration, loss of adoption | 2 | +| Security flaw: privacy related | leak user data, unlikely to achieve adoption in serious orgs | 5 | +| Security flaw: permissions escalation | expose user to malware | 5 | +| Code not addressing user needs | no product market fit, loss of adoption | 5 | +| Communication failures within team | Conflicting or duplicating work, frustration, morale damage | 4 | +| Communication failures with community | we lose product market fit, we do not have good community retention, reputational damage | 3 | +| Communication failures with leadership | product does not meet business goals | 3 | +| License compliance failures, including in supply chain (e.g. exposing privileged api responses for free via a plugin) | 4 | +| Bugs affecting releases | users stuck on old versions | 2 | +| Strategy failures | no product market fit | 2 | + +The mapping of severity to label is as follows: + +| Severity | Label | +| -------- | ----- | +| 1 | L | +| 2 | M | +| 3 | M | +| 4 | H | +| 5 | H | + +During the bug triage we will also discuss a remediation plan for the bug. This will be communicated in the comments on the bug report. For high urgency bugs, the fix wilkl be implemented as soon as possible, maybe reorganizing our current work to accommodate the fix. For medium priority bugs, we will schedule the fix in the next available sprint. Low priority bugs will be backlogged and addressed when there is developer time available. Low priority bugs will also be tagged `help-wanted` so that they can be addressed by community members. + +Not every bug will be fixed. We may decide *not* to fix a bug in cases such as: + +- fixing the bug has some detrimental side effect elsewhere in the product +- the bug has a fix coming soon as part of another upgrade +- the bug is only problematic for a single specific use casea nd fixing it would break features relied upon by other users +- the bug is contentious for some reason and there is reputational or community risks associated with the fix + +The bug will be labelled `fix-now`, `fix-later` or `wont-fix` to reflect our remediation plan and details will be provided in issue comments. + + + ## Code Contributions From 398f1d17b1d3736d2dada4d36c3f9e5ac8851e65 Mon Sep 17 00:00:00 2001 From: jmc <33655003+jmcook1186@users.noreply.github.com> Date: Wed, 24 Apr 2024 15:03:27 +0100 Subject: [PATCH 2/7] fix(package): fix typos --- CONTRIBUTING.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 79c75d35f..4f903c095 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,9 +37,11 @@ We appreciate bug reports! If you experience an issue with IF or one of our plug 3. Click on `Create New Issue` and select the `Bug Report` template. 4. Fill out the requested information. -The more detailed information you provide int hen bug report, the easier it will be for us to diagnose, triage and resolve your issue. We ask for some simple information about your issue, including a description of the error, the expected behaviour, the actual behaviour and the stepos we cna take to reproduce the error in our local environments. We also then prompt you to provide a link to [Stackblitz]() or a similar online environemnt where we can run your mnaifest and observe the error. If you prefer *not* to send a link, we would appreciate the a copy of the manifest file that you ran to produce the error, information about your runtime environment and any additional code that's required to reproduce. This is all designed to enable us to reproduce the same error and debug it for you. +The more detailed information you provide int hen bug report, the easier it will be for us to diagnose, triage and resolve your issue. We ask for some simple information about your issue, including a description of the error, the expected behaviour, the actual behaviour and the stepos we cna take to reproduce the error in our local environments. We also then prompt you to provide a link to [Stackblitz](https://stackblitz.com/) or a similar online environemnt where we can run your mnaifest and observe the error. If you prefer *not* to send a link, we would appreciate a copy of the manifest file that you ran to produce the error, information about your runtime environment and any additional code that's required to reproduce the error. This is all designed to enable us to reproduce the same error and debug it for you as quickly as possible. -Once a suitably detailed bug report exists, we will triage it. Triage means that the core team will assign an urgency label to your bug report - either Low, Medium or High. The assessment rubric is as follows: +Once a suitably detailed bug report exists, we will triage it. We hold weekly triage calls on Tuesdays. In most cases, the triage call will be the core team's first interaction with the bug, although in some cases we may enagge asynchronously in advance of the call. Triage means that the core team will examine the issue and assign an urgency label - either Low, Medium or High. + +The assessment rubric is as follows: | | Consequence | Severity | | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------- | @@ -68,7 +70,7 @@ The mapping of severity to label is as follows: | 4 | H | | 5 | H | -During the bug triage we will also discuss a remediation plan for the bug. This will be communicated in the comments on the bug report. For high urgency bugs, the fix wilkl be implemented as soon as possible, maybe reorganizing our current work to accommodate the fix. For medium priority bugs, we will schedule the fix in the next available sprint. Low priority bugs will be backlogged and addressed when there is developer time available. Low priority bugs will also be tagged `help-wanted` so that they can be addressed by community members. +During the bug triage we will also discuss a remediation plan for the bug. This will be communicated in the comments on the bug report. For high urgency bugs, the fix will be implemented as soon as possible, maybe reorganizing our current work to accommodate it. For medium priority bugs, we will schedule the fix in the next available sprint. Low priority bugs will be backlogged and addressed when there is developer time available. Low priority bugs will also be tagged `help-wanted` so that they can be addressed by community members. Not every bug will be fixed. We may decide *not* to fix a bug in cases such as: @@ -80,8 +82,6 @@ Not every bug will be fixed. We may decide *not* to fix a bug in cases such as: The bug will be labelled `fix-now`, `fix-later` or `wont-fix` to reflect our remediation plan and details will be provided in issue comments. - - ## Code Contributions ### Step 1: Fork From 9ede05160d6c60c548ae4db5445ea532e9e098f6 Mon Sep 17 00:00:00 2001 From: jmc <33655003+jmcook1186@users.noreply.github.com> Date: Wed, 24 Apr 2024 15:05:36 +0100 Subject: [PATCH 3/7] fix(package): fix another typo --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4f903c095..7f0613bdf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,7 +39,7 @@ We appreciate bug reports! If you experience an issue with IF or one of our plug The more detailed information you provide int hen bug report, the easier it will be for us to diagnose, triage and resolve your issue. We ask for some simple information about your issue, including a description of the error, the expected behaviour, the actual behaviour and the stepos we cna take to reproduce the error in our local environments. We also then prompt you to provide a link to [Stackblitz](https://stackblitz.com/) or a similar online environemnt where we can run your mnaifest and observe the error. If you prefer *not* to send a link, we would appreciate a copy of the manifest file that you ran to produce the error, information about your runtime environment and any additional code that's required to reproduce the error. This is all designed to enable us to reproduce the same error and debug it for you as quickly as possible. -Once a suitably detailed bug report exists, we will triage it. We hold weekly triage calls on Tuesdays. In most cases, the triage call will be the core team's first interaction with the bug, although in some cases we may enagge asynchronously in advance of the call. Triage means that the core team will examine the issue and assign an urgency label - either Low, Medium or High. +Once a suitably detailed bug report exists, we will triage it. We hold weekly triage calls on Tuesdays. In most cases, the triage call will be the core team's first interaction with the bug, although in some cases we may engage asynchronously in advance of the call. Triage means that the core team will examine the issue and assign an urgency label - either Low, Medium or High. The assessment rubric is as follows: From eec5159047cefecb22ab5b2cd7e70b02540d9bf0 Mon Sep 17 00:00:00 2001 From: jmc <33655003+jmcook1186@users.noreply.github.com> Date: Wed, 24 Apr 2024 15:12:30 +0100 Subject: [PATCH 4/7] feat(package): add bug reporting guidance to readme --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index a300a2603..717cd08ee 100644 --- a/README.md +++ b/README.md @@ -105,3 +105,9 @@ You can check our issue board for issues tagged `help-wanted`. These are issues Please read the full contribution guidelines at [if.greensoftware.foundation](https://if.greensoftware.foundation/Contributing) The same guidelines also apply to `if-docs`, `if-plugins` and `if-unofficial-plugins`. + +## Bug reports + +To report bugs please use our bug report template. You can do this by opening a new issue and selecting `Bug Report` when you are prompted to pick a template. The more information you provide,.the quicker we will be able to reproduce, diagnose and triage your issue. + +To read about our bug reporting and triage process, please see [our contribution guidelines](contributing.md#reporting-bugs). From c6b897ef802814ddf4def00f3bdc44a81027b200 Mon Sep 17 00:00:00 2001 From: jmc <33655003+jmcook1186@users.noreply.github.com> Date: Thu, 25 Apr 2024 09:02:52 +0100 Subject: [PATCH 5/7] fix(package): clarify some bug tyypes in table --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7f0613bdf..5746413ba 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,9 +45,9 @@ The assessment rubric is as follows: | | Consequence | Severity | | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------- | -| Bugs in IF core | unusable framework, incorrect calculations | 5 | -| Bugs in if-plugins | core pathways fail, IF very limited in functionality | 5 | -| Bugs in if-unofficial | Third party plugins harder to use, limits IF to standard lib | 3 | +| Bugs in IF core leading to incorrect calculations | unusable framework | 5 | +| Bugs in if-plugins leading to incorrect calculations | core pathways fail, IF very limited in functionality | 5 | +| Bugs in if-unofficial-pluginsd leading to incorrect calculations | Third party plugins harder to use, limits IF to standard lib | 3 | | Bugs in template | Harder to build plugins, ecosystem growth is impacted | 2 | | Bugs in docs | product does not match expectation, hard to debug, frustration, loss of adoption | 2 | | Security flaw: privacy related | leak user data, unlikely to achieve adoption in serious orgs | 5 | From 0b271f21909008b9a0d117c4eaf2321a19fa79bf Mon Sep 17 00:00:00 2001 From: jmc <33655003+jmcook1186@users.noreply.github.com> Date: Thu, 25 Apr 2024 09:03:24 +0100 Subject: [PATCH 6/7] fix(package): fix typo in contributing doc --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5746413ba..39ddebdb1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,7 +37,7 @@ We appreciate bug reports! If you experience an issue with IF or one of our plug 3. Click on `Create New Issue` and select the `Bug Report` template. 4. Fill out the requested information. -The more detailed information you provide int hen bug report, the easier it will be for us to diagnose, triage and resolve your issue. We ask for some simple information about your issue, including a description of the error, the expected behaviour, the actual behaviour and the stepos we cna take to reproduce the error in our local environments. We also then prompt you to provide a link to [Stackblitz](https://stackblitz.com/) or a similar online environemnt where we can run your mnaifest and observe the error. If you prefer *not* to send a link, we would appreciate a copy of the manifest file that you ran to produce the error, information about your runtime environment and any additional code that's required to reproduce the error. This is all designed to enable us to reproduce the same error and debug it for you as quickly as possible. +The more detailed information you provide in then bug report, the easier it will be for us to diagnose, triage and resolve your issue. We ask for some simple information about your issue, including a description of the error, the expected behaviour, the actual behaviour and the stepos we cna take to reproduce the error in our local environments. We also then prompt you to provide a link to [Stackblitz](https://stackblitz.com/) or a similar online environemnt where we can run your mnaifest and observe the error. If you prefer *not* to send a link, we would appreciate a copy of the manifest file that you ran to produce the error, information about your runtime environment and any additional code that's required to reproduce the error. This is all designed to enable us to reproduce the same error and debug it for you as quickly as possible. Once a suitably detailed bug report exists, we will triage it. We hold weekly triage calls on Tuesdays. In most cases, the triage call will be the core team's first interaction with the bug, although in some cases we may engage asynchronously in advance of the call. Triage means that the core team will examine the issue and assign an urgency label - either Low, Medium or High. From fe31f94aed56679202ba42afa14384443084b541 Mon Sep 17 00:00:00 2001 From: Joseph Cook <33655003+jmcook1186@users.noreply.github.com> Date: Thu, 25 Apr 2024 20:54:29 +0100 Subject: [PATCH 7/7] Apply suggestions from code review Signed-off-by: Joseph Cook <33655003+jmcook1186@users.noreply.github.com> --- CONTRIBUTING.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 39ddebdb1..85d06491b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,18 +26,18 @@ The following document is a rule set of guidelines for contributing. ## What and when to contribute -You can contribute anything to the IF, but we are likely to close out unsolicited PRs without merging them. Our issue board is completely open and we have tags (`help-wanted`, `good-first-issue`) to help contributors to choose tasks to work on. We recommend speaking to the core team on Github before starting working on an issue. You can do this by raising an issue or commenting on an existing issue. This helps us to direct your energy is directions that are aligned with our roadmap, prevent multiple people working on the same task, and better manage our board. This all makes it much more likely that your work will get merged. +You can contribute anything to the IF, but we are likely to close out unsolicited PRs without merging them. Our issue board is completely open and we have tags (`help-wanted`, `good-first-issue`) to help contributors to choose tasks to work on. We recommend speaking to the core team on Github before starting working on an issue. You can do this by raising an issue or commenting on an existing issue. This helps us to direct your energy in directions that are aligned with our roadmap, prevent multiple people working on the same task, and better manage our board. This all makes it much more likely that your work will get merged. ## Reporting bugs We appreciate bug reports! If you experience an issue with IF or one of our plugins, you can report it using our bug reporting template. To do this: -1. Go to the [IF repository](https://github.com/Green-Software-Foundation/if) (or [plugin repository](https://github.com/Green-Software-Foundation/if) if you bug relates to a specific plugin) +1. Go to the [IF repository](https://github.com/Green-Software-Foundation/if) (or [plugin repository](https://github.com/Green-Software-Foundation/if-plugins) if you bug relates to a specific plugin) 2. Click on the `Issues` tab 3. Click on `Create New Issue` and select the `Bug Report` template. 4. Fill out the requested information. -The more detailed information you provide in then bug report, the easier it will be for us to diagnose, triage and resolve your issue. We ask for some simple information about your issue, including a description of the error, the expected behaviour, the actual behaviour and the stepos we cna take to reproduce the error in our local environments. We also then prompt you to provide a link to [Stackblitz](https://stackblitz.com/) or a similar online environemnt where we can run your mnaifest and observe the error. If you prefer *not* to send a link, we would appreciate a copy of the manifest file that you ran to produce the error, information about your runtime environment and any additional code that's required to reproduce the error. This is all designed to enable us to reproduce the same error and debug it for you as quickly as possible. +The more detailed information you provide in the bug report, the easier it will be for us to diagnose, triage and resolve your issue. We ask for some simple information about your issue, including a description of the error, the expected behaviour, the actual behaviour and the stepos we can take to reproduce the error in our local environments. We also then prompt you to provide a link to [Stackblitz](https://stackblitz.com/) or a similar online environment where we can run your manifest and observe the error. If you prefer *not* to send a link, we would appreciate a copy of the manifest file that you ran to produce the error, information about your runtime environment and any additional code that's required to reproduce the error. This is all designed to enable us to reproduce the same error and debug it for you as quickly as possible. Once a suitably detailed bug report exists, we will triage it. We hold weekly triage calls on Tuesdays. In most cases, the triage call will be the core team's first interaction with the bug, although in some cases we may engage asynchronously in advance of the call. Triage means that the core team will examine the issue and assign an urgency label - either Low, Medium or High. @@ -57,7 +57,7 @@ The assessment rubric is as follows: | Communication failures with community | we lose product market fit, we do not have good community retention, reputational damage | 3 | | Communication failures with leadership | product does not meet business goals | 3 | | License compliance failures, including in supply chain (e.g. exposing privileged api responses for free via a plugin) | 4 | -| Bugs affecting releases | users stuck on old versions | 2 | +| Bugs affecting releases | users stuck on old versions | 4 | | Strategy failures | no product market fit | 2 | The mapping of severity to label is as follows: @@ -76,7 +76,7 @@ Not every bug will be fixed. We may decide *not* to fix a bug in cases such as: - fixing the bug has some detrimental side effect elsewhere in the product - the bug has a fix coming soon as part of another upgrade -- the bug is only problematic for a single specific use casea nd fixing it would break features relied upon by other users +- the bug is only problematic for a single specific use case and fixing it would break features relied upon by other users - the bug is contentious for some reason and there is reputational or community risks associated with the fix The bug will be labelled `fix-now`, `fix-later` or `wont-fix` to reflect our remediation plan and details will be provided in issue comments.