Prepare the upgrade to 2.0 (1.7)

[lyrixx]

gitlib 1.7 prepares the upgrade to 2.0, the way Symfony prepares its majors: it has the API of 2.0 that can be added without breaking 1.x, and deprecates what 2.0 replaces or breaks, with the messages of 2.0. Code without deprecations with 1.7 runs with 2.0 too, so a library can require ^1.7 || ^2.0 with a single code path. With it, phpro/grumphp#1235 drops its class_exists() branches and its Psalm suppressions.

The CHANGELOG.md lists everything. In short:

• CliDriver and new Repository($dir, $workingDir, $driver), the static methods of Repository (init(), cloneFrom()…) instead of Admin;
• getDiff($from, $to), getMergeBase(), Diff::parse($raw, $repository), FileChange::getDiffLines() with DiffLine and the DiffLineType enum;
• iterating a Tree, which gives TreeEntry objects, with getBlobs(), getTrees() and getSubmodules();
• Log::withLimit(), Blame::getHunks(), Branch::isMergedInto() and moveTo(), PushReference::isCreation(), getSizeInBytes()…

Nothing of 1.6 breaks

The aim is that upgrading from 1.6 to 1.7 is safe, so it follows the BC promise of Symfony, and is stricter on parameter names:

• the parameters keep their names, for named arguments;
• the arguments added to the methods of classes that aren't final are read with func_get_arg(), commented out in their signature, with @psalm-variadic, so the classes overriding these methods keep working;
• gitlib keeps calling the deprecated methods a subclass overrides, when 1.6 called them itself;
• what 2.0 makes final is @final since gitonomy/gitlib 1.7.

BackwardCompatibilityTest checks these. The test suite of v1.6.0, unchanged, passes on this code, except 3 tests: testGetSize, which fails on v1.6.0 already with git 2.53, and 2 tests whose error handler refuses any deprecation but the one they expect.

1.7 requires PHP 8.1, for the DiffLineType enum: on PHP 8.0, Composer keeps 1.6. It requires symfony/deprecation-contracts.

What 1.7 can't bring

A few changes of 2.0 would break 1.x. They will be listed in the UPGRADE-2.0.md of main: the numbering of Blame::getLines() with a range, reading the references again after run(), \DateTimeImmutable dates, the stricter diff parser…

Next steps

1. Tag v1.7.0 on 1.x.
2. Merge 1.x into main with git merge -s ours: main keeps its tree and gets 1.7 as an ancestor, with no force push.
3. Open the pull request on main so that 2.0 introduces no deprecation of its own (all are since 1.7), with the "Supporting 1.x and 2.x" section of UPGRADE-2.0.md.