Inconsistent reference documentation on republication of incomplete event publications

[breun]

https://docs.spring.io/spring-modulith/reference/events.html#publication-registry says: "By default, all incomplete event publications are resubmitted at application startup."

However, https://docs.spring.io/spring-modulith/reference/appendix.html#configuration-properties says that the default value for spring.modulith.republish-outstanding-events-on-restart is false. This is indeed also specified in the Spring configuration metadata. This seems to contradict the first statement.

Looking at the implementation of org.springframework.modulith.events.support.PersistentApplicationEventMulticaster#afterSingletonsInstantiated it looks like incomplete publications are only resubmitted when spring.modulith.republish-outstanding-events-on-restart is explicitly set to true.

[odrotbohm]

Your observation is correct. The former, erroneous section stems from the time when the default was the opposite before we flipped the flag for improved production-readiness.

[breun]

I see you added this in the documentation: "Usually not recommended in multi-instance deployments as other instances might still be processing events." What is the recommended way to deal with this for multi-instance deployments?

[odrotbohm]

Some application component using @Scheduled and IncompleteEventPublications as currently you cannot differentiate between publications currently in process versus ones that have failed. Thus, you'd usually resubmit only publications older than a certain time frame, depending on how long you expect the listeners to take. Furthermore, you'd have to guard against multiple instances processing the outstanding evens by using something like SchedLock.

We are tracking improvements to the publication lifecycle in GH-796 and a better out-of-the-box locking experience but without any concrete plans yet.

[breun]

This sounds like a pretty risky pitfall for users that may think multi-instance setups will currently Just Work™ (like myself until today).

Would it be an idea to document the things that multi-instance applications will currently need to take care of themselves (maybe with some recommendations/examples)?