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 new file mode 100644 index 00000000000..c86dda44715 --- /dev/null +++ b/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). 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