fix(caldav): Restore old private events and deprecate them

[nickvergessen]

Summary

• Avoiding the unnecessary BC break from feat(dav)!: add webhook compatibility for calendar object events #51082 as the events are more used then assumed and "defacto" public API.
• We can remove them in 33 or 34, to reduce maintenance effort but still allowing apps/consumers a smooth transition

Checklist

• Code is properly formatted
• Sign-off message is added to all commits
• Tests (unit, integration, api and/or acceptance) are included
• Screenshots before/after for front-end changes
• Documentation (manuals or wiki) has been updated or is not required
• Backports requested where applicable (ex: critical bugfixes)

[ChristophWurst]

I disagree that events are defacto public API. This slows down internal changes, because you never know if something is used by an app.
The public/private namespace distinction is there to solve this precise problem.

It's the same dilemma as calling every OCS API a public API. This leads to nobody building a proper public API, and implicitly causing breaking changes when internal OCS APIs change.

IMHO this is not the right way to move forward as a platform.

I'm okay with restoring the previous events for stable31.

[AndyScherzinger]

I am fine either way, but definitely needs to ensure we do not break v31, so 32 I could live with while I also don't see an issue in dropping with v33 or v34. It would be deprecated evens with a 31 change, so we can communicate it and drop it, no fixes on old API, hence no maintenance and folks can move over to the new one.

Let me know if you need a decision.

[nickvergessen]

The public/private namespace distinction is there to solve this precise problem.

This option does not exist for apps. We can not merge every interface and event that should be "public" from Talk or all 300+ other apps into the server repo.

It's the same dilemma as calling every OCS API a public API. This leads to nobody building a proper public API, and implicitly causing breaking changes when internal OCS APIs change.

Talk has one of the biggest APIs and basically all of it (apart from HPB sign-up admin only feature) is OCS and documented with openapi and follows the default retention period. It's doable at least.

We also don't need to over play it here. In this case here it's a simple event (or well 6), we can avoid breaking things by keeping 6 files a tad longer. It's a drop-in replacement with a name change, so should also be fine to require changing it earlier, not 3 years needed. But on a patch version is meh, as apps would need to subscribe to both events etc.
I will add my commit to the backport only.

🫧 Future

Happy to discuss alternatives, but we need events, they should be "contractual save" at least some of them (seeing many OCA\…\Event\LoadAdditionalScriptsEvent and …\BeforeTemplateRenderedEvent for files, settings, …) and many others are used by other apps. For the future I'd propose that events should have @internal when they are meant to only be internal and this should be limited to "where strictly required", all other events should have proper @since and @deprecated annotations and follow "decent" documentation and deprecation policies. The ecosystem lives from integrations between apps and those need to be possible without a big hassle.

[JonathanTreffler]

To actually solve the bigger issue behind this I would advocate for the addition of a public namespace for apps so basically OCAP and OCA with the same meaning of OC and OCP. I am not entirely sure how this would work on a technical level, as the classloader would of course have to be adjusted (maybe a public directory in the lib folder 🤷 ).

An alternative would of course be to have an #[internal] or similar class attribute as @nickvergessen proposed, but I would go further than just events. I think there are many legitimate cases for calling another apps service class for example.

I call OCA APIs in my apps all the time (and I will not apologize 😆) (often between multiple apps by me, so I myself can keep the interfaces stable which helps, but most apps don't change their interfaces often anyways), even though it is not technically public, because that is the only sane way apps can cooperate and extend each other currently (the only alternative would often be to query and change other apps databases, sooooo no thank you, OCA it is).