From e663d2ea5fd4b5e930b195fa3e69ab6e90188102 Mon Sep 17 00:00:00 2001 From: Anna Petrasova Date: Wed, 8 Feb 2023 22:42:19 -0500 Subject: [PATCH 1/5] RFC: Errata --- doc/development/rfc/errata.md | 50 +++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 doc/development/rfc/errata.md diff --git a/doc/development/rfc/errata.md b/doc/development/rfc/errata.md new file mode 100644 index 00000000000..cbd85aa7899 --- /dev/null +++ b/doc/development/rfc/errata.md @@ -0,0 +1,50 @@ +# RFC 5: GRASS GIS Errata + +Author of the first draft: Māris Nartišs + +Status: Early draft (19 Mar 2016) + +## Introduction + +GRASS GIS is widely used in scientific, private and government sector. Scientific theories, environmental decisions and actions depend on the outcome of spatial analysis performed with GRASS GIS. Any errors in analytical modules might lead to erroneous conclusions and actions based on them. This RFC provides a framework of documenting and spreading information on analysis inaccuracies caused by errors in GRASS GIS code. + +## Overall process + +1. Any bug reporter or developer can nominate a bug for escalating to GRASS GIS erratum issue. Nomination is done by adding a notice to bug at bug tracker or discussing directly at developer mailing list. Any nomination is discussed in developer mailing list to gather necessary information on it's scope, impact, causes and solutions. + +2. GRASS PSC evaluates nomination based on information provided by bug report, discussion in developer mailing list and/or other sources. PSC makes a final decision if nominated bug matches criteria of issuing a GRASS GIS erratum. + +3. A draft of erratum text is made in a designated area of developer wiki (issue tracker) holding texts of all published GRASS GIS errata. + +4. After a review of at least one more person, the erratum is marked as final one and spread via communication channels. + +### Evaluation criteria + + * Bug must be present in an official GRASS GIS release. + * Bug must cause generation of incorrect analysis results that are not so easy to notice. +Module crashes or bugs causing easy to identify incorrect results should not be given an erratum. Examples of possible erratum worth bugs are single cell shift of raster result, not enough randomness of expected random module output, loss of output precision due to incorrect floating point handling etc. + +### Content and life cycle of an Erratum + +GRASS GIS Erratum message should contain following elements: + * it's number; + * date of issue; + * name(s) of affected module(s); + * information about affected release(s); + * a short description of problem; + * steps resulting in incorrect output (i.e. specific input parameter combination); + * current state of problem (in progress, fixed for release x.y.z); + * references to bug report (Trac bug number), developer mailing list thread; + * any other information relevant to erratum. + +GRASS GIS errata might receive updates, if it's found to be necessary +(i.e. notice of fixing issue, issue scope update etc.). + +### Spreading the word + +All GRASS GIS errata texts should be available at two places - developer wiki (Trac) and ERRATA file of any upcoming release. +Errata should be listed in time descending order (latest on the top). + +If the erratum was based on a bug report in issue tracker, a notice to the issue report should be added. + +Announcement of the erratum should be sent out to XXXX mailing list. From 461441c3a7f307603a1f7fcdd5ae73f5f876a717 Mon Sep 17 00:00:00 2001 From: Anna Petrasova Date: Thu, 9 Feb 2023 09:43:01 -0500 Subject: [PATCH 2/5] linting --- doc/development/rfc/errata.md | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/doc/development/rfc/errata.md b/doc/development/rfc/errata.md index cbd85aa7899..40da2dff6ff 100644 --- a/doc/development/rfc/errata.md +++ b/doc/development/rfc/errata.md @@ -6,7 +6,8 @@ Status: Early draft (19 Mar 2016) ## Introduction -GRASS GIS is widely used in scientific, private and government sector. Scientific theories, environmental decisions and actions depend on the outcome of spatial analysis performed with GRASS GIS. Any errors in analytical modules might lead to erroneous conclusions and actions based on them. This RFC provides a framework of documenting and spreading information on analysis inaccuracies caused by errors in GRASS GIS code. +GRASS GIS is widely used in scientific, private and government sector. Scientific theories, environmental decisions and actions depend on the outcome of spatial analysis performed with GRASS GIS. Any errors in analytical modules might lead to erroneous conclusions and actions based on them. +This RFC provides a framework of documenting and spreading information on analysis inaccuracies caused by errors in GRASS GIS code. ## Overall process @@ -20,22 +21,23 @@ GRASS GIS is widely used in scientific, private and government sector. Scientifi ### Evaluation criteria - * Bug must be present in an official GRASS GIS release. - * Bug must cause generation of incorrect analysis results that are not so easy to notice. +* Bug must be present in an official GRASS GIS release. +* Bug must cause generation of incorrect analysis results that are not so easy to notice. Module crashes or bugs causing easy to identify incorrect results should not be given an erratum. Examples of possible erratum worth bugs are single cell shift of raster result, not enough randomness of expected random module output, loss of output precision due to incorrect floating point handling etc. ### Content and life cycle of an Erratum GRASS GIS Erratum message should contain following elements: - * it's number; - * date of issue; - * name(s) of affected module(s); - * information about affected release(s); - * a short description of problem; - * steps resulting in incorrect output (i.e. specific input parameter combination); - * current state of problem (in progress, fixed for release x.y.z); - * references to bug report (Trac bug number), developer mailing list thread; - * any other information relevant to erratum. + +* it's number; +* date of issue; +* name(s) of affected module(s); +* information about affected release(s); +* a short description of problem; +* steps resulting in incorrect output (i.e. specific input parameter combination); +* current state of problem (in progress, fixed for release x.y.z); +* references to bug report (Trac bug number), developer mailing list thread; +* any other information relevant to erratum. GRASS GIS errata might receive updates, if it's found to be necessary (i.e. notice of fixing issue, issue scope update etc.). From b3fcd7444b7fffc5361408323e8405dd3c8ba842 Mon Sep 17 00:00:00 2001 From: Anna Petrasova Date: Thu, 9 Feb 2023 10:09:52 -0500 Subject: [PATCH 3/5] linting --- doc/development/rfc/errata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development/rfc/errata.md b/doc/development/rfc/errata.md index 40da2dff6ff..a7075f46fb3 100644 --- a/doc/development/rfc/errata.md +++ b/doc/development/rfc/errata.md @@ -6,7 +6,7 @@ Status: Early draft (19 Mar 2016) ## Introduction -GRASS GIS is widely used in scientific, private and government sector. Scientific theories, environmental decisions and actions depend on the outcome of spatial analysis performed with GRASS GIS. Any errors in analytical modules might lead to erroneous conclusions and actions based on them. +GRASS GIS is widely used in scientific, private and government sector. Scientific theories, environmental decisions and actions depend on the outcome of spatial analysis performed with GRASS GIS. Any errors in analytical modules might lead to erroneous conclusions and actions based on them. This RFC provides a framework of documenting and spreading information on analysis inaccuracies caused by errors in GRASS GIS code. ## Overall process From 00ff550839fb46fc8abc1af5092aa5c40501729c Mon Sep 17 00:00:00 2001 From: Nicklas Larsson Date: Tue, 28 Feb 2023 20:40:47 +0100 Subject: [PATCH 4/5] limit line width to 80 cols --- doc/development/rfc/errata.md | 40 +++++++++++++++++++++++++---------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/doc/development/rfc/errata.md b/doc/development/rfc/errata.md index a7075f46fb3..45d53f6ec37 100644 --- a/doc/development/rfc/errata.md +++ b/doc/development/rfc/errata.md @@ -6,24 +6,40 @@ Status: Early draft (19 Mar 2016) ## Introduction -GRASS GIS is widely used in scientific, private and government sector. Scientific theories, environmental decisions and actions depend on the outcome of spatial analysis performed with GRASS GIS. Any errors in analytical modules might lead to erroneous conclusions and actions based on them. -This RFC provides a framework of documenting and spreading information on analysis inaccuracies caused by errors in GRASS GIS code. +GRASS GIS is widely used in scientific, private and government sector. +Scientific theories, environmental decisions and actions depend on the outcome +of spatial analysis performed with GRASS GIS. Any errors in analytical modules +might lead to erroneous conclusions and actions based on them. This RFC +provides a framework of documenting and spreading information on analysis +inaccuracies caused by errors in GRASS GIS code. ## Overall process -1. Any bug reporter or developer can nominate a bug for escalating to GRASS GIS erratum issue. Nomination is done by adding a notice to bug at bug tracker or discussing directly at developer mailing list. Any nomination is discussed in developer mailing list to gather necessary information on it's scope, impact, causes and solutions. +1. Any bug reporter or developer can nominate a bug for escalating to GRASS GIS + erratum issue. Nomination is done by adding a notice to bug at bug tracker + or discussing directly at developer mailing list. Any nomination is + discussed in developer mailing list to gather necessary information on it's + scope, impact, causes and solutions. -2. GRASS PSC evaluates nomination based on information provided by bug report, discussion in developer mailing list and/or other sources. PSC makes a final decision if nominated bug matches criteria of issuing a GRASS GIS erratum. +2. GRASS PSC evaluates nomination based on information provided by bug report, + discussion in developer mailing list and/or other sources. PSC makes a final + decision if nominated bug matches criteria of issuing a GRASS GIS erratum. -3. A draft of erratum text is made in a designated area of developer wiki (issue tracker) holding texts of all published GRASS GIS errata. +3. A draft of erratum text is made in a designated area of developer wiki + (issue tracker) holding texts of all published GRASS GIS errata. -4. After a review of at least one more person, the erratum is marked as final one and spread via communication channels. +4. After a review of at least one more person, the erratum is marked as final + one and spread via communication channels. ### Evaluation criteria * Bug must be present in an official GRASS GIS release. -* Bug must cause generation of incorrect analysis results that are not so easy to notice. -Module crashes or bugs causing easy to identify incorrect results should not be given an erratum. Examples of possible erratum worth bugs are single cell shift of raster result, not enough randomness of expected random module output, loss of output precision due to incorrect floating point handling etc. +* Bug must cause generation of incorrect analysis results that are not so easy + to notice. Module crashes or bugs causing easy to identify incorrect results + should not be given an erratum. Examples of possible erratum worth bugs are + single cell shift of raster result, not enough randomness of expected random + module output, loss of output precision due to incorrect floating point + handling etc. ### Content and life cycle of an Erratum @@ -44,9 +60,11 @@ GRASS GIS errata might receive updates, if it's found to be necessary ### Spreading the word -All GRASS GIS errata texts should be available at two places - developer wiki (Trac) and ERRATA file of any upcoming release. -Errata should be listed in time descending order (latest on the top). +All GRASS GIS errata texts should be available at two places - developer wiki +(Trac) and ERRATA file of any upcoming release. Errata should be listed in time +descending order (latest on the top). -If the erratum was based on a bug report in issue tracker, a notice to the issue report should be added. +If the erratum was based on a bug report in issue tracker, a notice to the +issue report should be added. Announcement of the erratum should be sent out to XXXX mailing list. From 2da66ce1838f80ad9672f9637c0e0e26c510b925 Mon Sep 17 00:00:00 2001 From: Anna Petrasova Date: Tue, 25 Aug 2026 17:00:36 -0400 Subject: [PATCH 5/5] update errata to better match current approach --- doc/development/rfc/README.md | 2 +- doc/development/rfc/errata.md | 94 ++++++++++++++--------------------- doc/howto_release.md | 12 +++-- 3 files changed, 47 insertions(+), 61 deletions(-) diff --git a/doc/development/rfc/README.md b/doc/development/rfc/README.md index 5ee9ff1d805..765ece58a4b 100644 --- a/doc/development/rfc/README.md +++ b/doc/development/rfc/README.md @@ -11,7 +11,7 @@ A list of all GRASS GIS RFC documents, with status: (Adopted) - [RFC 3: PSC Voting Procedures](PSC_voting_procedures.md) (Adopted) - [RFC 4: Release Procedure](https://github.com/OSGeo/grass/pull/2815) (Draft) -- [RFC 5: GRASS GIS Errata](https://github.com/OSGeo/grass/pull/2813) (Draft) +- [RFC 5: Errata](errata.md) (Draft) - [RFC 6: Migration from SVN to GitHub](migration_github.md) (Adopted) - [RFC 7: Language Standards Support](language_standards_support.md) (Adopted) - [RFC 8: Python Language Support](python_language_support.md) (Adopted) diff --git a/doc/development/rfc/errata.md b/doc/development/rfc/errata.md index 45d53f6ec37..c86dda44715 100644 --- a/doc/development/rfc/errata.md +++ b/doc/development/rfc/errata.md @@ -1,70 +1,50 @@ -# RFC 5: GRASS GIS Errata +# RFC 5: Errata -Author of the first draft: Māris Nartišs +Status: Draft -Status: Early draft (19 Mar 2016) +## Summary -## Introduction +Some bugs make GRASS produce results which are wrong but look plausible. Users +who already ran an affected analysis, and published or acted on its results, +need a way to find out. This RFC describes how such fixes are marked and how +the resulting errata reach users. -GRASS GIS is widely used in scientific, private and government sector. -Scientific theories, environmental decisions and actions depend on the outcome -of spatial analysis performed with GRASS GIS. Any errors in analytical modules -might lead to erroneous conclusions and actions based on them. This RFC -provides a framework of documenting and spreading information on analysis -inaccuracies caused by errors in GRASS GIS code. +## What qualifies as an erratum -## Overall process +An erratum is issued for a bug which -1. Any bug reporter or developer can nominate a bug for escalating to GRASS GIS - erratum issue. Nomination is done by adding a notice to bug at bug tracker - or discussing directly at developer mailing list. Any nomination is - discussed in developer mailing list to gather necessary information on it's - scope, impact, causes and solutions. +* is present in an official GRASS release, and +* causes incorrect analysis results which are not easy to notice. -2. GRASS PSC evaluates nomination based on information provided by bug report, - discussion in developer mailing list and/or other sources. PSC makes a final - decision if nominated bug matches criteria of issuing a GRASS GIS erratum. +Crashes, error messages and obviously wrong output are ordinary bugs, not +errata, because users can see that something went wrong. Typical errata are a +single cell shift of a raster result, loss of precision due to incorrect +floating point handling, or a wrong conversion factor. A bug introduced and +fixed between two releases does not need an erratum, since no release is +affected. -3. A draft of erratum text is made in a designated area of developer wiki - (issue tracker) holding texts of all published GRASS GIS errata. +## Process -4. After a review of at least one more person, the erratum is marked as final - one and spread via communication channels. +1. The pull request fixing the bug gets the `errata` label. Anyone can add it: + the author, a reviewer, or whoever merges the fix. There is no separate + nomination or approval step. When it is not clear whether a fix qualifies, + it is discussed in the pull request like any other review question. -### Evaluation criteria +2. The pull request description explains the problem for users, not only for + developers: which tools are affected, which released versions are affected, + what was computed incorrectly, and how users can tell whether their own + results are affected. The person who fixed the bug writes this while the + details are fresh. -* Bug must be present in an official GRASS GIS release. -* Bug must cause generation of incorrect analysis results that are not so easy - to notice. Module crashes or bugs causing easy to identify incorrect results - should not be given an erratum. Examples of possible erratum worth bugs are - single cell shift of raster result, not enough randomness of expected random - module output, loss of output precision due to incorrect floating point - handling etc. +3. The fix is backported to the supported release branches so that users + receive it. When it cannot be backported, the description says which + versions stay affected. -### Content and life cycle of an Erratum +4. The release notes of the release containing the fix get an `Errata` section + listing the labeled fixes, using the user-facing wording from step 2 and + linking to the pull request. The + [8.4.2 release notes](https://github.com/OSGeo/grass/releases/tag/8.4.2) + are an example. -GRASS GIS Erratum message should contain following elements: - -* it's number; -* date of issue; -* name(s) of affected module(s); -* information about affected release(s); -* a short description of problem; -* steps resulting in incorrect output (i.e. specific input parameter combination); -* current state of problem (in progress, fixed for release x.y.z); -* references to bug report (Trac bug number), developer mailing list thread; -* any other information relevant to erratum. - -GRASS GIS errata might receive updates, if it's found to be necessary -(i.e. notice of fixing issue, issue scope update etc.). - -### Spreading the word - -All GRASS GIS errata texts should be available at two places - developer wiki -(Trac) and ERRATA file of any upcoming release. Errata should be listed in time -descending order (latest on the top). - -If the erratum was based on a bug report in issue tracker, a notice to the -issue report should be added. - -Announcement of the erratum should be sent out to XXXX mailing list. +The list of errata across releases is the +[merged pull requests with the errata label](https://github.com/OSGeo/grass/pulls?q=is%3Apr+is%3Amerged+label%3Aerrata). diff --git a/doc/howto_release.md b/doc/howto_release.md index e8b4866ec22..5438eca7300 100644 --- a/doc/howto_release.md +++ b/doc/howto_release.md @@ -216,9 +216,14 @@ added manually to the result from the _api_ backend. The script sorts them into categories defined in _utils/release.yml_. However, these notes need to be manually edited to collapse related items into one. Additionally, a _Highlights_ section needs to be added on top with manually -identified new major features for major and minor releases. For all releases, a -_Major_ section may need to be added showing critical fixes or breaking changes -if there are any. +identified new major features for major and minor releases. Breaking changes +and updated requirements are listed there as well. + +For all releases, an _Errata_ section needs to be added if the release contains +fixes of bugs which produced wrong results in an earlier release. These are the +merged pull requests labeled `errata`; describe each one in terms of what was +computed incorrectly, so that users can tell whether their own results are +affected. See [RFC 5: Errata](development/rfc/errata.md). ### Modify the release draft @@ -286,6 +291,7 @@ The published RC releases have the initial release notes (based on locally auto-generated notes) which need to be refined further: - add highlights +- add errata - verify that the subsections are well sorted For the final release, edit this draft release again in order to publish it