From 087c416419dde5c2cf444122e231911406ff9679 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Mon, 30 Oct 2023 14:52:33 +0000 Subject: [PATCH 1/4] add a section about severity level to the guidelines --- README.adoc | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index 4550bac0..e7cfae43 100644 --- a/README.adoc +++ b/README.adoc @@ -87,7 +87,7 @@ Each error and notification comprises the following components, some of which ar | For example, `The database was unable to execute a remote part of the statement.` | SeverityLevel -| +| See <>. | One of `INFORMATION`\|`WARNING` m| ERROR @@ -174,6 +174,15 @@ See <>. | The label `Perso` does not exist. |=== +[[severity-level]] +==== Severity level + +The severity can be one of the following: + +* `WARNING`: The query may have issues. Please review it. We might be able to give you a suggestion on how to improve it. +* `INFORMATION`: The query may have issues, even though it is correct. The provided information can still be helpful. +* `ERROR`: The query execution failed. Please review the query. We might be able to give you a suggestion on how to improve it. + [[notification-description]] ==== Notification description From 4bce67dc7231a50c0407123632fc8560e65053e9 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 1 Nov 2023 10:26:33 +0000 Subject: [PATCH 2/4] add more details to the severity level --- README.adoc | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/README.adoc b/README.adoc index e7cfae43..8a227a5a 100644 --- a/README.adoc +++ b/README.adoc @@ -179,9 +179,14 @@ See <>. The severity can be one of the following: -* `WARNING`: The query may have issues. Please review it. We might be able to give you a suggestion on how to improve it. -* `INFORMATION`: The query may have issues, even though it is correct. The provided information can still be helpful. -* `ERROR`: The query execution failed. Please review the query. We might be able to give you a suggestion on how to improve it. +* `WARNING`: It is about queries/commands that may have structural, syntactic, semantic, or spelling issues that prevent them from being executed in an optimal way. +It's good to tell the user what the problem is, the possible cause, and the consequences, as well as give an example(s) and suggestion(s) for improvement. + +* `INFORMATION`: It is about queries/commands that are correct but may have some performance issues or that have no effect because they try to do something already done. +Depending on the case, we may give an example(s) and suggestion(s) for improvement. + +* `ERROR`: It is about queries/commands that fail to succeed. +It's good to tell the user what triggers the error, an example, and a possible solution(s). [[notification-description]] ==== Notification description From bf443234105fb63cac4481f83c0e21abef1ff0e9 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 1 Nov 2023 11:59:37 +0000 Subject: [PATCH 3/4] apply suggestion from review --- README.adoc | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/README.adoc b/README.adoc index 8a227a5a..8bad5880 100644 --- a/README.adoc +++ b/README.adoc @@ -179,8 +179,14 @@ See <>. The severity can be one of the following: -* `WARNING`: It is about queries/commands that may have structural, syntactic, semantic, or spelling issues that prevent them from being executed in an optimal way. -It's good to tell the user what the problem is, the possible cause, and the consequences, as well as give an example(s) and suggestion(s) for improvement. +* `WARNING`: It is about queries/commands that may have structural, syntactic, semantic, or spelling issues where the query most probably is wrong and/or should be updated. +This includes deprecations, experimental features, trying to match on entities with non-existing labels, etc. +It should be clear what the problem is and it is also good to tell the possible cause, and the consequences, as well as give an example(s) and suggestion(s) for improvement. +I think the most important part is that "we are (almost) certain it is a problem" and we know how to fix your query. So for: + +** Deprecations – you need to update the query with new functionallity. +** Experimental features – These can not be trusted and should be updated if used in production. +** Non-existing label – This query will never give any result, so it's either useless to run OR a misspelled label (unless you add a node with the label, but then the notification would disappear). * `INFORMATION`: It is about queries/commands that are correct but may have some performance issues or that have no effect because they try to do something already done. Depending on the case, we may give an example(s) and suggestion(s) for improvement. From 420ab9d18edf8267d391c60128970de05616705e Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Thu, 2 Nov 2023 11:26:09 +0000 Subject: [PATCH 4/4] fix the wording --- README.adoc | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/README.adoc b/README.adoc index 8bad5880..f8448f6e 100644 --- a/README.adoc +++ b/README.adoc @@ -180,13 +180,14 @@ See <>. The severity can be one of the following: * `WARNING`: It is about queries/commands that may have structural, syntactic, semantic, or spelling issues where the query most probably is wrong and/or should be updated. -This includes deprecations, experimental features, trying to match on entities with non-existing labels, etc. +This includes deprecations, experimental features, trying to match entities with non-existing labels, etc. It should be clear what the problem is and it is also good to tell the possible cause, and the consequences, as well as give an example(s) and suggestion(s) for improvement. -I think the most important part is that "we are (almost) certain it is a problem" and we know how to fix your query. So for: +The most important part is that "we are (almost) certain it is a problem" and we know how to fix their query. +For example: -** Deprecations – you need to update the query with new functionallity. -** Experimental features – These can not be trusted and should be updated if used in production. -** Non-existing label – This query will never give any result, so it's either useless to run OR a misspelled label (unless you add a node with the label, but then the notification would disappear). +** Deprecations – The users need to update the query with new functionality. +** Experimental features – These cannot be trusted and should be updated if used in production. +** Non-existing label – This query will never give any result, so it's either useless to run OR a misspelled label (unless they add a node with the label, but then the notification would disappear). * `INFORMATION`: It is about queries/commands that are correct but may have some performance issues or that have no effect because they try to do something already done. Depending on the case, we may give an example(s) and suggestion(s) for improvement.