Add action typing declaration

[krzema12]

Pilot for typesafegithub/github-workflows-kt#302

Not necessarily for merging as is, but as a starting point for further discussion
and another round of feedback.

[Vampire]

Is this really necessary?
Isn't the custom file already sign enough that it is following the github-actions-typing spec?
If the spec evolves in a backwards incompatible way, then maybe a simple version key or similar would be enough?
And as long as only backwards compatible changes are done, just assuming a default version should be enough?

[krzema12]

Yeah, thanks for bringing it up, I keep thinking if it's a good idea to have this value. The idea is that as long github-actions-typing is at v0.x, breaking changes may happen (e.g. I'll change casing according to your suggestion). By having this field I wanted the consumers to be able to depend on v0 (not pin to minor version) and the action would know how to validate all versions we had along the way.

If you, as an early adopter, are fine with occasional breaking changes and a need to bump typing validation action, then I'm fine with what you propose. Once we consider the typing spec stable (v1), version key won't yet be needed, and we could postpone introducing it until v2 if it has breaking changes.

[krzema12]

typesafegithub/github-actions-typing#11

[Vampire]

If you, as an early adopter, are fine with occasional breaking changes and a need to bump typing validation action

I guess I can live with that, especially as I don't expect too many v0 breaking changes, and I'm sure you will create PRs for them. :-)

[Vampire]

Would you expect more sub-keys for listItem?
Otherwise maybe just a listItemType key, or list-item-type, or similar directly?

[krzema12]

Yes, there can be more, e.g. for an enum (see here) or an integer with named values. In terms of typing, whatever goes under listItem behaves similarly like action's input/output. The only limitation for now is that list items cannot themselves be lists - I want to keep it simple for now. No use case for List<List<List<String>>> appeared yet 😉

[jmfayard]

No use case for List<Boolean> either :)
imagine - enable: [true, false]
or - enable: [true, true]
or - enable: []

[krzema12]

Yeah, we could simplify it further and allow lists of only integers and enums - I wanted to do it initially. However, then I asked myself what if we allow basic types there, and forbid only nesting lists because then it may become more tricky. So allowing e.g. List<Boolean> stems from the idea of supporting lists of basic types, not having a real-life use case for it :) Would you guys recommend limiting lists only to lists of strings and enums? We can always extend it later.

[krzema12]

FTR, this discussion doesn't seem to be relevant for the decision if there should be list-item: with subkeys or list-item-type: because the enum kinda requires the former.

[jmfayard]

list-item feels better to me

[Vampire]

Ah, right, yeah, if you need more subkeys potentially like for enums, list-item is fine of course.
I think I'd not limit the subtype (further than forbidding lists unless someone comes up with a use-case).
If someone wants a list of booleans, why not, if you don't need special code to support it and I guess you don't , or at least not significant.

[Vampire]

The standard keys in action and workflow files follow kebab-case,
maybe this file should also use it instead of camelCase?

[krzema12]

GitHub is not very consistent when it comes to casing - apart form what you wrote, I've seen snake_case as well. But you're right that kebab-case is the most frequent casing, let me change it in the whole typing spec.

[krzema12]

typesafegithub/github-actions-typing#10

[Vampire]

Actually they even have one case I have seen where they used camelCase, for deprecationMessage. :-D
But yeah, most is kebab-case, that's what I meant. :-)

[krzema12]

Thanks for great hints! I applied them in 6d17d07, but without necessary changes in the validation action yet. Will wait for a "ship it" from your side, then will adjust the action, and then we can rerun the checks and merge.

[Vampire]

Will wait for a "ship it" from your side, then will adjust the action, and then we can rerun the checks and merge.

I think it looks good to me spec-wise.
I'll probably fiddle a bit about the formatting like sprinkling in some newlines and remove the quotes of strings where not necessary, but I can do that to my liking, no need to micro-manage there. :-)

Btw. do you use a parser that allows usage of YAML anchors?
It might happen that someone defines a list of possible enum values and then later has onther input with a list of the same enum values, so it would be nice if the validation action and the consuming code would be able to use YAML anchors, unlike GitHub actions themselves.
Another good reason to have it in a separate file. :-)

[krzema12]

Btw. do you use a parser that allows usage of YAML anchors?

I use kaml. According to this, it supports anchors. I haven't tested it yet, though. Thanks for the hint!

[Vampire]

Yes, kaml fully supports anchors.
Maybe you remember I told you I use kaml currently to parse my workflow template with extensive anchor usage and then again to write it out to have it flattened out like GitHub Actions requires it. :-)

Would be nice if that is a documented guarantee in the spec and not just an accidental implementation detail. :-)
This way we can nail you on it if you happen to change to something not supporting them. :-D

[krzema12]

Would be nice if that is a documented guarantee in the spec and not just an accidental implementation detail. :-)
This way we can nail you on it if you happen to change to something not supporting them. :-D

Got it, sure thing: typesafegithub/github-actions-typing#12

[krzema12]

@Vampire I've adjusted the action - feel free to restart the workflows.

Note: please don't set the verbose flag, I'll remove it soon in favor of debug logging you proposed.

[krzema12]

Yay, works!