Include coauthors in GitHub repos

[j3soon]

Completely implements #44 (along with #61).

Solution Description:

• If no commit message includes co-authors, then the plugin behavior stays exactly the same.
• If one of the commit message includes co-authors, then the plugin will check if a GitHub token exists.
  • If no GitHub token exists, the plugin outputs a warning, and keep the original behavior.
  • If a GitHub token exists, the plugin sends a GraphQL query to reliably retrieve all co-authors info and include them to the author list.

Design Choices:

I considered a few implementations and decided to use REST API by default, switching to GraphQL only when necessary.

Some considerations:

• Always using GraphQL is not preferred since it requires users to provide a GitHub token. Therefore, we still want to use the REST API by default, allow using this plugin even when no GitHub tokens are provided.
• Not using GraphQL entirely will require manually determining the co-authors info, which is very error-prone.

References & Further Details:

• Co-authors can only be retrieved through GraphQL (https://docs.github.com/en/graphql/reference/objects#commit) and not from REST APIs (https://docs.github.com/en/rest/commits/commits?apiVersion=2022-11-28), as defined in their API specs, and discussed here: https://github.com/orgs/community/discussions/30313 .
• It is possible to somehow manually parse the commit message retrieved through the REST API and perform a GitHub user look up, but it would be very unreliable. Looking up by commit author name results in frequent mismatch, while looking up by commit author email only works when the email is the user's public email.
• Alternatively, list-contributors URI (described in #16 and #38) may be more reliable, but cannot be used in private GitHub repositories.
• The GraphQL query code is mainly modified based on commit https://github.com/ojacques/mkdocs-git-committers-plugin-2/commit/806e422bdf59bbefd995f243be275b9661d78d2f
• The Co-authored-by: commit message is parsed and displayed in GitHub web UI: https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors

[ojacques]

Yes, I moved back from graphql to indeed make it really simple for anyone who does not need advanced use cases. I would consider coauthors to be one of those advanced use case, hence graphql usage seems perfectly fine to me.

Could you please

• Resolve the conflict now that #61 is merged?
• Add few lines in the doc about this great new addition?

Thanks!

[j3soon]

Thanks for the quick reply! Just resolved the conflicts and updated the docs.

It's also worth noting that these two PRs only fixes #44 for GitHub repos, not for GitLab repos yet.

[lancehaig]

Just adding my +1

[ojacques]

Thank you for this great add.