RFC: Errata

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)

doc/development/rfc/errata.md

@@ -0,0 +1,50 @@
+# RFC 5: Errata
+
+Status: Draft
+
+## Summary
+
+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.
+
+## What qualifies as an erratum
+
+An erratum is issued for a bug which
+
+* is present in an official GRASS release, and
+* causes incorrect analysis results which are not easy to notice.
+
+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.
+
+## Process
+
+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.
+
+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.
+
+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.
+
+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.
+
+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).

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