Expand event lifecycle documentation

[aahlenst]

Explicitly discuss the event lifecycle and some of its consequences that are not obvious, at least based on my experience and some of the issues.

Feel free to take what you like. I'm also happy to revise the documentation based on feedback.

[aahlenst]

That should be "Spring Modulith Event Registry Starters", shouldn't it? Otherwise, I'm unsure what the relation to Spring Boot is.

[odrotbohm]

The reason we say "Spring Boot" here is that the notion of starter POMs was introduced by Boot, and usually referred to as "Spring Boot starters for …". But I agree that we could change that to "Spring Modulith … starters".

[odrotbohm]

I appreciate the suggestions but let's hold off from further submissions like these right now. There is a reason, the documentation is currently pretty thin on this particular topic. That reason is that we don't want to give incomplete guidance on topics like resubmissions, which is what your proposed edits do. They don't work properly in multi-instance application deployments and there are multiple, different means of solving that. Until we get to a decision, which of them we prefer to recommend, we would have to litter our docs with all the variants to avoid the impression of us taking a stance.

That said, be reminded that this is the Spring Modulith reference documentation. We want to avoid diverging into general technical advise, what additional code to add to your application. I'll take your suggestions to the team (also #929) and take it from there.

[aahlenst]

That reason is that we don't want to give incomplete guidance on topics like resubmissions, which is what your proposed edits do.

I do not intend to provide recommendations on resubmissions or anything else but to document the properties of the event system, like delivery guarantees or the event lifecycle. Currently, the documentation says little about it or you have to read between the lines. That makes it unnecessarily hard to figure out how to fit Modulith into an application. From my point of view, the documentation of the event system should provide more details in the following areas:

• What is the event lifecycle, and what are the implications?
• What delivery guarantees does Modulith provide?
• How does Modulith integrate with Spring's application events? What happens when you use parts that are not mentioned in Modulith's documentation?
• How does the event system deal with event classes that have been removed or (de-)serialize into a different shape?
• What type of deployments or usages does Modulith not support, at least not at the moment?
• What areas of Modulith are purposefully underdocumented or areas of exploration?

Neither of those points is about providing recommendations. I am fully aware that applications (and people) can have very different needs. For example, I'm not interested in multi-instance applications while others are. Not having an answer (right now) can be perfectly fine, too.

I can imagine that some of my edits might be interpreted differently, so let's improve them.

That said, be reminded that this is the Spring Modulith reference documentation. We want to avoid diverging into general technical advise, what additional code to add to your application.

It is hard to argue without specifics, but there's no disagreement about the reference documentation aspect, rather about its execution. For example, the code sample I included is there to provide an usage example for IncompleteEventPublications because "They are available as Spring Beans" is a bit short. And if I remember correctly, its usage is not shown in the official Modulith examples, either. We don't have to go as far as Framework does by including interface declarations, but having explicit usage examples is very helpful.