Metadata question

[stevehipwell]

I happened to be re-implementing some acceptance tests the other day and while doing so I noticed that the signatures for the actions secret functions didn't look right. Tracking this back into the OpenAPI doc shows that the 5 functions below are tracking APIs from GHES v3.7 that are no longer documented (see #4335 for my proposed fix for this specific case).

• ActionsService.GetEnvPublicKey
• ActionsService.ListEnvSecrets
• ActionsService.GetEnvSecret
• ActionsService.CreateOrUpdateEnvSecret
• ActionsService.DeleteEnvSecret

Looking at the OpenAPI metadata I was expecting these endpoints to be marked as deprecated, but this doesn't appear to be the case. I can also see unused endpoints from old GHES versions still in the metadata.

My primary questions are as follows:

• Should endpoints be removed once they're no longer supported by GitHub and are no longer in use (e.g. there are some projects v1 endpoints still in there)?
• Should endpoints be marked as deprecated once they're no longer supported by GitHub (e.g. deprecated or not in supported GHES versions)?
• If the endpoints were correctly marked as deprecated would this automatically mark the functions as deprecated?
  • If this is the case do we have a process for updating functions that just need to change endpoint and/or signature?

[stevehipwell]

CC @gmlewis

[gmlewis]

• Should endpoints be removed once they're no longer supported by GitHub and are no longer in use (e.g. there are some projects v1 endpoints still in there)?

This topic has been discussed many times in this repo over the years.
The bottom line is that we have challenges removing deprecated endpoints in this repo because after a release someone will say "Hey, I'm still running GitHub Enterprise version X.Y.Z and we still rely on these endpoints that you just removed!" at which point we tell them to pin this repo to a version that supports it, but then they say, "Yes, but version D.E.F of go-github fixed a bug in method G.H which we also really need!"
So the easiest thing to do over the years is to NOT remove deprecated endpoints so that our dear Enterprise users (which there are WAY more of than I had ever imagined there would be) do not get upset.

• Should endpoints be marked as deprecated once they're no longer supported by GitHub (e.g. deprecated or not in supported GHES versions)?

Yes, they should, and lately we have been attempting to do that.

• If the endpoints were correctly marked as deprecated would this automatically mark the functions as deprecated?

Yes, our "tools/metadata" program does this.

• If this is the case do we have a process for updating functions that just need to change endpoint and/or signature?

Yes, our occasional updates to openapi_operations.yaml do this. For example, we just did this here:
https://github.com/google/go-github/pull/4331/changes

Or am I not understanding your questions correctly?

[stevehipwell]

RE removal, I can see endpoints in the metadata that are unused and haven't been supported since GHES v3.4 or something similar.

RE automation, I mean automation to flag the functions that I'm fixing in #4335 as no longer being documented or supported given that there is nothing newer than GHES v3.7?

[gmlewis]

RE removal, I can see endpoints in the metadata that are unused and haven't been supported since GHES v3.4 or something similar.

Yes, true.

RE automation, I mean automation to flag the functions that I'm fixing in #4335 as no longer being documented or supported given that there is nothing newer than GHES v3.7?

If the official GitHub v3 API docs mark them as "deprecated" then when we update "openapi_operations.yaml," they will be marked as "deprecated".

[gmlewis]

RE automation, I mean automation to flag the functions that I'm fixing in #4335 as no longer being documented or supported given that there is nothing newer than GHES v3.7?

If the official GitHub v3 API docs mark them as "deprecated" then when we update "openapi_operations.yaml," they will be marked as "deprecated".

Meanwhile, you can also manually mark methods as "deprecated" in the comments. That is fine too.

[stevehipwell]

If the official GitHub v3 API docs mark them as "deprecated" then when we update "openapi_operations.yaml," they will be marked as "deprecated".

@gmlewis if an endpoint isn't in the DotCom, GHEC or latest GHES schema then shouldn't we mark it as deprecated?

Based on that logic I make it 46 endpoints that aren't currently deprecated but could/should be deprecated (yq eval '[.openapi_operations[] | select(((.deprecated // false) | not) and (((.openapi_files // []) | contains(["descriptions/api.github.com/api.github.com.json"])) or ((.openapi_files // []) | contains(["descriptions/ghes-3.21/ghes-3.21.json"])) or ((.openapi_files // []) | contains(["descriptions/ghec/ghec.json"]))) | not)]' openapi_operations.yaml).

[gmlewis]

@gmlewis if an endpoint isn't in the DotCom, GHEC or latest GHES schema then shouldn't we mark it as deprecated?

Yes, that seems reasonable to me.

[stevehipwell]

For completeness I'm using this command to mark the metadata as deprecated yq eval -i '(.openapi_operations[] | select(((.deprecated // false) | not) and (((.openapi_files // []) | contains(["descriptions/api.github.com/api.github.com.json"]) | not) and ((.openapi_files // []) | contains(["descriptions/ghes-3.21/ghes-3.21.json"]) | not) and ((.openapi_files // []) | contains(["descriptions/ghec/ghec.json"]) | not))).deprecated) = true' openapi_operations.yaml.

[stevehipwell]

@gmlewis would it be possible/practical to validate the function URLs based on the meta:operation comment? I'm thinking along the lines of this:

• Find meta:operation comment
  • Tokenize URL by /
• Find url declaration
  • Tokenize URL by /
• Compare tokens
  • %v == {.+}

[gmlewis]

@gmlewis would it be possible/practical to validate the function URLs based on the meta:operation comment?

If it were me, instead of writing another tool that attempts to find the meta:operation comments and URLs,
I would probably attempt to tap into the tools/metadata tool that actually generates/validates the meta:operation lines and URLs directly and take advantage of all that non-trivial logic that we know already works.

[stevehipwell]

@gmlewis that's kind of what I was asking, I was looking for a steer. After looking at the code to update the deprecations I think I can see how it could be added in.