Add workflow to determine API changes and comment on PRs

[Xtansia]

Description

Adds a workflow that determines the API changes introduced by a PR and then comments on the PR with a summary of the changes a long with a link to a full HTML based report. If a comment already exists it will edit it rather than creating a new one.

Examples

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[github-actions]

API specs implemented for 307/649 (47%) APIs.
Commit c6f2cf2.

[dblock]

We already have https://github.com/opensearch-project/opensearch-api-specification/blob/main/.github/workflows/coverage-api.yml and https://github.com/opensearch-project/opensearch-api-specification/blob/main/.github/workflows/coverage-comment.yml, how do you feel about combining these? All you need is the interesting parts of .github/workflows/determine-changes.yml (can be in its own workflow) and the commenting logic of editing/updating is already fully implemented. Or move the coverage workflow gathering into this one?

One advantage of that workflow is that it will re-create the comment after the change, so that it's not confusing to which commit it refers.

[Xtansia]

We already have https://github.com/opensearch-project/opensearch-api-specification/blob/main/.github/workflows/coverage-api.yml and https://github.com/opensearch-project/opensearch-api-specification/blob/main/.github/workflows/coverage-comment.yml, how do you feel about combining these? All you need is the interesting parts of .github/workflows/determine-changes.yml (can be in its own workflow) and the commenting logic of editing/updating is already fully implemented. Or move the coverage workflow gathering into this one?

One advantage of that workflow is that it will re-create the comment after the change, so that it's not confusing to which commit it refers.

When you say combine do you mean as a single comment containing both pieces of information or just combining logic/workflow?

I personally prefer editing the existing comment rather than deleting & recreating as it cuts down on the notification/email spam and also means you get "free" history record via the comment's edit history (albeit expiring after some time). This is how codecov does its coverage comments. As long as the comment body contains the sha then there's no confusion. It also means its likely to always be the first comment and stay there rather than moving over time and get lost between other comments.

[dblock]

When you say combine do you mean as a single comment containing both pieces of information or just combining logic/workflow?

I think we should combine both pieces of information. Changes and coverage are very related, I'd be happy if you want to take the coverage parts and add them to this PR (and delete the existing workflows).

I personally prefer editing the existing comment rather than deleting & recreating as it cuts down on the notification/email spam and also means you get "free" history record via the comment's edit history (albeit expiring after some time). This is how codecov does its coverage comments. As long as the comment body contains the sha then there's no confusion. It also means its likely to always be the first comment and stay there rather than moving over time and get lost between other comments.

Sounds good, no strong feelings about this.

[dblock]

This looks good.

Write up how these things work in various READMEs (README, dev guide, etc.), especially cookbooks on running some of the coverage itself locally so that one doesn't have to dig through workflow files for examples to copy-paste from.

[dblock]

Since we're writing tools here, would add a JS tool to wait for OpenSearch to start that polls.

[dblock]

You could use SHAs instead of ORIGINAL and CHANGED to avoid confusion, running over old data, etc.

[Xtansia]

@dblock I still need to do the documentation, however I've rearchitected things a bit further and now have comments like below. I think this would be a good point to get some of your feedback on how you feel about the approach before I write everything up now that it's basically complete. I've potentially gone overkill with trying to generalize the actual PR commenting side of the workflow. 😅

[dblock]

It's pretty crazy but I like it. Avoid more feature creep and finish this PR :)

[dblock]

I'd name this templates for future templates.

[dblock]

In general, I think this is a good blueprint for a service that provides OpenAPI spec coverage, sounds like a nice pet project!