Add action typings

[krzema12]

Changes

• add action typings according to https://github.com/krzema12/github-actions-typing/

Context

GitHub's actions generally lack a standardized way to expose information about types of their inputs and outputs. It's hard both for the users and for automation that may want to rely on it. Thanks to https://github.com/krzema12/github-actions-typing/, types are provided in automation-friendly way. One of such pieces of automation is a Kotlin DSL for authoring GitHub workflows: https://github.com/krzema12/github-actions-kotlin-dsl

Ideally GitHub should provide a way of defining these in e. g. action.yml, but it's not supported yet. Adding typings using https://github.com/krzema12/github-actions-typing/ is an iterative step towards having the typings. Possibly one day first-class support from GitHub will be added, and until then the typings added in this PR can greatly help.

For more info, please read the project's README.

[krzema12]

@luketomlinson friendly ping 😄

[krzema12]

@rentziass @flaxel @JoannaaKL could you take a look at this PR?

[flaxel]

Nice addition to the project! 🎉

[krzema12]

@flaxel ready for another round of review 😄

[flaxel]

I took a look at some options and sometimes the type of the value didn't match. Maybe you can check again. 👀

[krzema12]

@flaxel feel free to point of an example.

[flaxel]

Oh sorry, I had two values mixed up. 🙈 Small note to me, no more work in the evening. 😆

[krzema12]

@Newman1515 I don't understand why the "test" workflow step failed. I've run npm run all and npm run pack and committed to this branch. Please approve the workflows, hopefully it will pass now. If it doesn't, I kindly ask you to help me fix the issue - this PR doesn't deal with this action's logic, it just adds the typings, so the dist/index.js shouldn't change.

[krzema12]

In a PR in my fork (here: krzema12#1) I got a green build:

[irega]

@Newman1515 I don't understand why the "test" workflow step failed. I've run npm run all and npm run pack and committed to this branch. Please approve the workflows, hopefully it will pass now. If it doesn't, I kindly ask you to help me fix the issue - this PR doesn't deal with this action's logic, it just adds the typings, so the dist/index.js shouldn't change.

@Newman1515 @krzema12 please check this PR, I debugged and fixed the issue with the test workflow there.

[krzema12]

@luketomlinson @rentziass @JoannaaKL @Newman151 friendly ping.

[krzema12]

@JoannaaKL @e-korolevskii could you take a look please? The PR on which this one waited for #859 has just got merged.

[JoannaaKL]

Thank you for this improvement!

[krzema12]

Thanks! @JoannaaKL could you merge? I have no permissions.

[krzema12]

@Newman1515 please take a look.

[krzema12]

@marko-zivic-93 @IvanZosimov thanks for approving! Could you merge?

[krzema12]

@marko-zivic-93 @IvanZosimov ping.

[krzema12]

@marko-zivic-93 @IvanZosimov ping.

[IvanZosimov]

Hi, @krzema12 👋 We are still investigating your PR, sorry for the late response. As soon as we finish we get back to you with updates.

[IvanZosimov]

Hi, @krzema12 👋 Sorry for the delay, we have investigated your PR. As we get it right, the action typings action goes through the action.yml and validates it according to the rules specified in the action-types.yml. Could you please provide us with any potential or valuable applications/use cases for this action? 

[krzema12]

@IvanZosimov sure!

The goal of this PR is in fact to add a piece of documentation. However, it's not yet another piece of Markdown. When working with various actions, I discovered that it's challenging to know what type of data is needed for the inputs of an action, the same for outputs. Every action has its own custom way of documenting it, if it documents it at all, which makes it challenging for humans and automation to work with various actions. I figured there must be a way to address it. actions/stale has 52 (!) inputs and 2 outputs. It's the most complicated action API I've ever saw. That's why I thought it will be a good candidate to receive proper API documentation regarding types.

I looked for an inspiration in other ecosystems where types were added later, like TypeScript adding types for JavaScript, or type hints in the Python world. I decided to create github-actions-typing which aspires to be the standardized way of typing your action's API. Onboarding is as easy as adding an extra action-types.yml file to your repository root, and (optionally, although highly recommended - I do it in this PR) adding a simple GitHub workflow that validates this new file. It has no negative effects on current action consumers, they continue to use the action as if the file wasn't there. An example project that uses the typings in its automation is a DSL for defining GitHub workflows in Kotlin in a type-safe way: github-workflows-kt. I can imagine one can use the typings to even provide better IDE support for authoring workflows in YAML.

Addressing your question specifically:

Could you please provide us with any potential or valuable applications/use cases for this action?

You correctly inferred that the goal of the action itself is to validate the typings, i.e. if each action input and output has a type assigned, and that the type is correct according to the standard. It works a bit like mypy in the Python world that allows adding static type checks over untyped API.

[IvanZosimov]

@krzema12, Thanks for the reasonable clarification! Unfortunately, we have to reject your PR, and there are some reasons why we made this decision:

1. Usually inputs and outputs of actions are well documented: there is the README.md which contains all needed information and examples of use, and the action.yml which gives a general understanding of the responsibility of each input. We don't think that additional documentation will improve the onboarding process.
2. Usually action inputs and outputs are covered by tests; in our opinion, tests are enough to validate values from the action.yml.

However, we are really thankful to you for your willingness to make our action better ❤️ 

[Vampire]

@IvanZosimov may I ask how you expect automation to recognize the types from the prose in README.md and action.yml?
That the action-types.yml is a clear and defined definition of types that could help individuals to onboard is a nice side effect.
But the main advantage of it is, that automation can use these types in an automated fashion.

For example the github-workflows-kt library which allows to write Workflow files in Kotlin DSL can read these type information and generate Kotlin files, so that you action can conveniently be used by users of that library.
And as there are other libraries for similar approaches in different programming languages already, those could then also use these formally defined type information to produce something convenient out of it.

[IvanZosimov]

@Vampire, Sorry, we fully understand your point, but at the moment, we aren't ready to accept this PR.

[Vampire]

Sad, but of course your decision.
As you say "at the moment", what would need to happen so that you would be ready to accept it? :-)