How to fix gradebook issues

Devdocsbot — Tue, 18 Aug 2026 05:14:30 GMT

Dev Docs Bot protected How to fix gradebook issues [Edit=Allow only administrators] (indefinite) Developer Docs Migration

← Older revision		Revision as of 05:14, 18 August 2026
(One intermediate revision by the same user not shown)
Line 1:		Line 1:
	~~==How to fix Grade book issues==~~		{{Template:Migrated\|newDocId=/general/development/process/gradebook-calculation-changes}}

	There has been a policy decision that any fixes to the grade book must not result in any changes to grades. Some fixes may result in grades being changed and in these situations we need to freeze the grade book and let the teacher / admin / higher power agree to applying the change.

	~~For future fixes to the grade book we will be putting revision numbers and nested code into the grade book libraries.~~

	~~===Fixing the issue===~~

	~~Choose a freeze number that is greater than the current build number but will be less than the next build number.~~

	~~When making changes wrap your code in an if statement.~~

	~~example:~~
	~~<syntaxhighlight lang="php">~~
	~~$gradebookcalculationsfreeze = get_config('core', 'gradebook_calculations_freeze_' . $courseid);~~
	~~// Stick with the original code if the grade book is frozen.~~
	~~if ($gradebookcalculationsfreeze && (int)$gradebookcalculationsfreeze <=~~ {~~your code freeze number})~~ {
	~~{original code goes here}~~
	~~} else {~~
	~~{new fixed code goes here}~~
	}
	~~</syntaxhighlight>~~
	~~Enter in details about your fix at https://docs.moodle.org/29/en/Gradebook_calculation_changes~~

	~~===Upgrade code===~~

	~~Code will be required to determine if the site being upgraded is affected. If so then it should be flagged to be frozen.~~

	~~example (lib/db/upgrade.php)~~:
	~~<syntaxhighlight lang~~=~~"php">~~
	~~if ($oldversion < 2015062500.01) {~~
	// ~~MDL-48239. Changed calculated grade items so that the maximum and minimum grade can be set.~~

	~~// If the changes are accepted and a regrade is done on the gradebook then some grades may change significantly.~~
	~~// This is here to freeze the gradebook in affected courses.~~

	// ~~This script is included in each major version upgrade~~ process ~~so make sure we don't run it twice.~~
	~~if (empty($CFG->upgrade_calculatedgradeitemsignored)) {~~
	~~upgrade_calculated_grade_items();~~

	~~// To skip running the same script on the upgrade to the next major release.~~
	~~set_config('upgrade_calculatedgradeitemsignored', 1);~~
	}

	~~// Main savepoint reached.~~
	~~upgrade_main_savepoint(true, 2015062500.01);~~
	}
	~~</syntaxhighlight>~~
	~~The code for doing this check should be located in lib/db~~/~~upgradelib.php so that it can also be run when a course is being restored.~~

	~~===New installations===~~

	~~Make sure to not run the upgrade step with the new installation~~

	~~example (lib/db/install.php:: xmldb_main_install() line 135):~~
	~~<syntaxhighlight lang="php">~~
	~~'upgrade_calculatedgradeitemsignored' => 1, // New installs should not run this upgrade step.~~
	~~</syntaxhighlight>~~

	~~===Restoration code===~~

	~~Code should be generated so that a regrading of the~~ gradebook ~~will fix the problem. Any solution that requires direct alteration of the grades in the database will result in an extremely complex set of restore code.~~

	~~example (backup/moodle2/restore_stepslib.php):~~
	~~<syntaxhighlight lang="php">~~
	~~// Calculated grade items need recalculating for backups made between 2.8 release (20141110) and the fix release (20150627).~~
	~~if (!$gradebookcalculationsfreeze && $backupbuild >= 20141110 && $backupbuild < 20150627) {~~
	~~require_once($CFG~~-~~>libdir . '/db/upgradelib.php');~~
	~~upgrade_calculated_grade_items($this~~-~~>get_courseid());~~
	}
	~~</syntaxhighlight>~~
	~~===Tests===~~

	~~Create a behat test to make sure that when the gradebook is frozen that grades are not changed.~~
	~~Create a behat test to make sure that when the gradebook is not frozen that the issue is solved.~~

	~~Create unit tests to check functions in the upgradelib.php file.~~

MoodleDocs - Recent changes [en]

How to fix gradebook issues