[codebyray]

Summary

Merges the completed v2.2.1 maintenance work from 2.x into master.

This is a non-breaking patch release focused on MySQL compatibility, safer migration publishing, and clearer rating API documentation.

Fixed

• Correct MySQL grouped-rating queries involving the reserved key column.
• Prevent repeated vendor:publish commands from creating duplicate timestamped migration files.

Maintenance

• Clarify the differences between:
  • averageRating('overall')
  • averageRatings()
  • overallAverageRating()
• Clarify that rating distributions count stored criterion values rather than reviews.
• Clarify that getReviewsByRating() matches a value in any rating criterion.
• Add migration-publishing regression coverage.
• Add a dedicated MySQL 8.4 compatibility CI job.
• Update the changelog for v2.2.1.

Compatibility

This release does not change public method signatures, contracts, configuration keys, or database schema.

Existing applications do not need to republish configuration or run additional migrations.

Verification

CI passes across:

• Laravel 10 / PHP 8.1
• Laravel 11 / PHP 8.2
• Laravel 12 / PHP 8.2
• Laravel 13 / PHP 8.3
• MySQL 8.4

After this PR is merged and CI passes on master, the resulting commit will be tagged as v2.2.1.