docs: add decision record about state machine manual interactions

[ndr-brt]

What this PR changes/adds

Adds a decision record about state machine manual interactions

Why it does that

Briefly state why the change was necessary.

Further notes

List other areas of code that have changed but are not necessarily linked to the main feature. This could be method
signature changes, package declarations, bugs that were encountered and were fixed inline, etc.

Linked Issue(s)

Part of #3308

Please be sure to take a look at the contributing guidelines and our etiquette for pull requests.

[wolf4ood]

🚀

[jimmarino]

I have two wording nits:

1. Can we call hook TransitionGuard or just Guard since it is a bit more descriptive?
2. instead of setWaitingForManualInteraction can we name it setWaitingOnGuard or a more generic term? This mechanism could be used for things other than manual interaction.

Otherwise LGTM.

[ndr-brt]

I have two wording nits:

1. Can we call hook TransitionGuard or just Guard since it is a bit more descriptive?
2. instead of setWaitingForManualInteraction can we name it setWaitingOnGuard or a more generic term? This mechanism could be used for things other than manual interaction.

Otherwise LGTM.

I agree on the Guard term, actually I like it more than hook.

Talking about the manual interaction, that's only a particular kind of guard that will only serve that precise scope, so in the entity I would still talking about "manual interaction" or something that reminds that.

[jimmarino]

I have two wording nits:

1. Can we call hook TransitionGuard or just Guard since it is a bit more descriptive?
2. instead of setWaitingForManualInteraction can we name it setWaitingOnGuard or a more generic term? This mechanism could be used for things other than manual interaction.

Otherwise LGTM.

I agree on the Guard term, actually I like it more than hook.

Talking about the manual interaction, that's only a particular kind of guard that will only serve that precise scope, so in the entity I would still talking about "manual interaction" or something that reminds that.

Would "external interaction" work? I'm looking for a more general term since it could be an external system that transitions the sm and not necessarily a manual interaction.

[ndr-brt]

I have two wording nits:

1. Can we call hook TransitionGuard or just Guard since it is a bit more descriptive?
2. instead of setWaitingForManualInteraction can we name it setWaitingOnGuard or a more generic term? This mechanism could be used for things other than manual interaction.

Otherwise LGTM.

I agree on the Guard term, actually I like it more than hook.
Talking about the manual interaction, that's only a particular kind of guard that will only serve that precise scope, so in the entity I would still talking about "manual interaction" or something that reminds that.

Would "external interaction" work? I'm looking for a more general term since it could be an external system that transitions the sm and not necessarily a manual interaction.

Good point, I'd say yes, also, it could also be called just "waiting", or "pending", like, a "pending contract negotiation" is a negotiation that's waiting for an external interaction, and having a simple term to call it will make everything easier to understand. what do you think?

[codecov-commenter]

Codecov Report

Patch and project coverage have no change.

Comparison is base (b6c5f4e) 71.91% compared to head (03a57bc) 71.91%.

❗ Your organization is not using the GitHub App Integration. As a result you may experience degraded service beginning May 15th. Please install the Github App Integration for your organization. Read more.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3318   +/-   ##
=======================================
  Coverage   71.91%   71.91%           
=======================================
  Files         810      810           
  Lines       16509    16513    +4     
  Branches      962      964    +2     
=======================================
+ Hits        11872    11876    +4     
  Misses       4236     4236           
  Partials      401      401           

see 1 file with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.