feat: adds reusable actions

[baywet]

This pull request adds reusable actions.

closes #238

Reusable actions are a much simpler iteration of anything previously proposed/iterated on:

• component actions that can define any field that are available in actions today EXCEPT FOR the target
• reference objects that have at least $ref and target in the actions array
• reference object MAY also override anything from the referenced reusable action (copy/update/remove/description)

This iteration is better than earlier proposals because it's as simple as we can possibly make it. (no matrix, no variables, no string interpolation, etc...)

[ralfhandl]

I like the general direction.

[baywet]

Feedback from the meeting from both @lornajane and @ralfhandl :

• add a peer block to parameters for the environment variables, this allows to set defaults and "declare" which variables are used. But this declaration is optional.
• add a peer "actions" in the components, that's defined as everything except for the target. So people can specify the target on reference. Reusable actions may use action templates in turns.

[ralfhandl]

Mostly wording and capitalization

[baywet]

@ralfhandl @lornajane I pushed another update a couple of minutes ago. I wasn't happy about the whole reusable actions vs action templates kind of thing. After chatting with @mikekistler internally I realized we could simply define a an action template reference object as "you can override anything from the resolved template in the reference" like JSON schema does to some extent. And keep things extra simple.

Let me know what you think!

[lornajane]

Had a more detailed pass at it this time, added a few comments for things we should take a second glance at (especially considering how much refactoring has been done on this one) but nothing fundamental I promise!

[baywet]

@lornajane thanks for the great suggestions here! I took the liberty of resolving the ones that I considered trivial. Let me know what you think!

[mikekistler]

Re-approving.

[mikekistler]

Looks good. 👍

[lornajane]

Sorry, I thought more about this since we last discussed it and I think I've changed my mind... The reusable action is more generic, and the action that refers to it is more specific. So the overlay action's description should be used if it has one, and we can fall back to the reusable action's description if it doesn't.

[baywet]

If I'm understanding your comment correctly, it should already be possible with the current wording?

When:

• the reusable action has a description, but not the reference, use the one in the reusable action
• the reusable action does not have a description, but the reference does, use the one from the reference.
• both have a description, use the one from the reference.

Is this not what you expect anymore? Is the current wording unclear with regards to the intent?

[lornajane]

I've read this a couple more times and I think it's the language that is confusing (I know I'm supposed to be helping with this, not making it more confusing!). I think part of the problem here is that we are referring to something as a "reference" that can define a target or a description alongside, but actually I think we should be referring to an "action" as defined in the actions section , or a "reusable action" as defined in the components section.

Specifically to the description field which I think is the only thing we can define in either location now: if only one or other location has it, use that, but if they both do then the action (defined in the actions: section) should be used, not the more generic one from the reusable action (defined in components.actions).

[baywet]

Suggested change

	In case a description is defined in `fields` of the referenced [Reusable Action Object](#reusable-action-object) and in the Reference Object, the description from the Reference Object MUST be used.
	In case a description is defined in `fields` of the referenced [Reusable Action Object](#reusable-action-object) and in the [Reusable Action Reference Object](#reusable-action-reference-object), the description from the Reusable Action Reference Object MUST be used.

Is this better?

And the reason why we have a Reusable Action Reference Object different from the Action Object is because of the difference in required fields between the two. @handrews and I didn't want to write a bunch of conditional requirements after the experience in OpenAPI parameters, headers, etc...