Port and improve legacy gradebook freezing documentation

data/migratedPages.yml

@@ -333,6 +333,9 @@ Grunt:
 Hardening_new_Roles_system:
 - filePath: "/docs/apis/subsystems/roles.md"
   slug: "/docs/apis/subsystems/roles"
+How_to_fix_gradebook_issues:
+- filePath: "/general/development/process/gradebook-calculation-changes.md"
+  slug: "/general/development/process/gradebook-calculation-changes"
 Inplace_editable:
 - filePath: "/docs/apis/subsystems/output/inplace.md"
   slug: "/docs/apis/subsystems/output/inplace"

general/development/process/gradebook-calculation-changes.md

@@ -0,0 +1,45 @@
+---
+title: Gradebook calculation changes
+description: Requirements for fixes which may change existing grades.
+tags:
+  - Processes
+  - Core development
+  - Gradebook
+sidebar_position: 6
+---
+
+Gradebook fixes must not change existing grades without the agreement of a teacher or administrator. When a fix may change calculated grades in an existing course, the gradebook must continue using the previous calculation until an authorised user accepts the change.
+
+This process is only required when a change may affect existing grades. Other gradebook fixes follow the normal development process.
+
+## Fixing a calculation issue {/* #fixing-a-calculation-issue */}
+
+Choose an ordered freeze number for the calculation revision, conventionally using `YYYYMMDD`. Use the same number in the code and in the user documentation.
+
+Keep the original calculation available while the affected course is frozen:
+
+```php
+$gradebookcalculationsfreeze = get_config('core', 'gradebook_calculations_freeze_' . $courseid);
+
+if ($gradebookcalculationsfreeze && (int) $gradebookcalculationsfreeze <= $freezenumber) {
+    // Use the original calculation.
+} else {
+    // Use the fixed calculation.
+}
+```
+
+Apply the frozen behaviour to every affected calculation, display, and editing path. Avoid repeatedly retrieving the freeze value inside grade-processing loops.
+
+During upgrade, identify affected courses and set `gradebook_calculations_freeze_[courseid]` to the freeze number only when a freeze is not already present. An existing earlier freeze must not be replaced by a later revision. Place reusable upgrade functions in `lib/db/upgradelib.php` so they can also be used when restoring courses.
+
+New installations must not be marked as affected. Include the current freeze state in course backups and restore it where appropriate. When restoring a backup created before the fix, use the backup build number to determine whether the calculation needs to be updated. Prefer a solution which can be applied by regrading the gradebook; directly altering grades in the database makes restoration significantly more complex.
+
+The freeze must only be removed when an authorised user accepts the change. Moodle will then regrade the course using the fixed calculation.
+
+## Documentation {/* #documentation */}
+
+Add details of the fix to [Gradebook calculation changes](https://docs.moodle.org/en/Gradebook_calculation_changes), including the freeze number, the possible effect on grades, and a link to the tracker issue.
+
+## Tests {/* #tests */}
+
+Add acceptance tests to confirm that grades remain unchanged while the gradebook is frozen and that the issue is fixed after the change is accepted. Add unit tests for any functions in `lib/db/upgradelib.php`. Cover affected and unaffected courses, preservation of an existing freeze, and backup and restore behaviour.

general/development/process/integration/clr.md

@@ -65,6 +65,7 @@ The Component lead review process requires you to:
 1. Ensure backwards compatibility is maintained. As a starting point backwards compatibility must always be maintained. Where backwards compatibility is affected it should be:
    1. Well discussed with evidence of justification
    1. Documented and communicated to the community
+   1. Changes which may alter existing grades must follow the [gradebook calculation changes](../gradebook-calculation-changes.md) process
 1. Ensure backwards compatibility with the Moodle mobile app. Especially in areas where the Moodle app uses pre-rendered content from the site (like Quiz or Lesson)
 1. Verify that components are correct and check the right people have been involved (for example, component maintainers)
 1. Tests - must be written to guide tester to verify the fix is working.

general/development/process/integration/index.md

@@ -56,6 +56,7 @@ accessible domain.)
 compatibility is affected it should be:
    1. Well discussed with evidence of justification
    2. Documented and communicated to the community
+   3. Changes which may alter existing grades must follow the [gradebook calculation changes](../gradebook-calculation-changes.md) process
 6. Ensure backwards compatibility with the Moodle mobile app. Especially in areas where the Moodle app uses pre-rendered content from
 the site (like Quiz or Lesson)
 7. Verify that components are correct and check the right people have been involved (e.g. component maintainers)

general/development/process/peer-review/index.md

@@ -24,6 +24,7 @@ These are points to consider while peer-reviewing issues. Further explanation be
 [] Language
 [] Accessibility
 [] Databases
+[] Gradebook calculations
 [] Performance and Clustering
 [] Security
 [] Privacy (see Privacy API)
@@ -131,6 +132,10 @@ Ensure that:
 - There are minimal DB calls (no excessive use of the DB); and
 - The code uses SQL compatible with all the supported DB engines (check all selected fields appear in an 'ORDER BY' clause).
 
+### Gradebook calculations {/* #gradebook-calculations */}
+
+If a change may alter existing grades, ensure that it follows the [gradebook calculation changes](../gradebook-calculation-changes.md) process.
+
 ### Performance and clustering {/* #performance-and-clustering */}
 
 It is easy to write code that works sufficiently well when you are working on either small sets of data or with a small number of active users. Picking performance issues can be quite difficult and can required a complex level of understanding of both the section of code being reviewed, but also other parts that interact with it.