Add a new section to the spec ("requirements", "best practices",...)

[fachat]

I think there is a section missing on best practices or requirements that a pariticipant must fulfill. For example #302 it was discussed that the participant can never timeout itself, but must go back to the LRA before cancellation. Such implicit assumptions on participant behaviour should be made explicit and explained, if not specified as a requirement.

[mmusgrov]

A few points:

1. We have an examples section in the spec for each feature/annotation.
2. Participants are allowed to finish in error states (FailedToCompensate/FailedToComplete) so they don't need to "go back to the LRA before cancellation" - see Figure 3. Participant State Model in the spec.
3. The requirements on participants is to respond in a spec compliant way when they are asked to compensate. The javadoc for the Compensate annotation describes what a participant needs to do in order to be spec compliant.

@fachat Were you looking for something more than these?

[mmusgrov]

More specifically, in the issue you referenced: the participant can independently complete or cancel. But it then must respond correctly when asked to compensate by remembering that it has already compensated or completed. If it did the opposite of what the LRA final state requires (eg if the participant completes but the LRA cancels then it needs to return FailedToCompensate when asked to compensate by the implementation. These requirements are part of the model and are already discussed in the specification document.

Note that there is also an option that allows a participant to leave the LRA early using the (@Leave annotation) and then the implementation will ignore this participant when the LRA is finished.

@fachat So participant requirements are already in the spec and we do not recommend any best practices other than to fulfil the spec requirements (perhaps we can add more examples to clarify spec usage). Will you indicate which part of #302 gave you a different understanding and we will include a note on the issue clarifying what was said on the issue that led to your understanding.

[mmusgrov]

@fatchat we would like to reject this issue. If you disagree with the evaluation provided in May please can you let us know?

[fatchat]

@mmusgrov I believe you meant to tag @fachat

[mmusgrov]

@fachat we would like to reject this issue. If you disagree with the evaluation provided in May please can you let us know?

[mmusgrov]

@mmusgrov I believe you meant to tag @fachat

Thanks for letting me know @fatchat