[RFC] Setting NCU\ for unstable/work-in-progress API

[ArtificialOwl]

This comes after some discussions regarding the implementation of IUserPreferences directly in public or in private first.
During the discussion we established that keeping the API in private helps future unexpected fix and modification that might occurs in the near future; however, it will also block people to test it from their apps.

The conclusion was to provide a namespace for in-progress API with rules between public and private

• by not using private API, developers are still encouraged to use and test the API in theirs apps
• by not using public API, developers stays alert that the API can change at any moment.
• once the testing API is set as stable, code is copied to OCP\ and previous code within NCT\ is marked as deprecated

[ChristophWurst]

A dedicated namespace means you have to change your app once the API switches from testing to stable. Would it be possible to put the APIs into the OCP namespace but tag them as @experimental or similar? Experimental could mean that the API exists for that release but there are no guarantees for stability. Future versions might have a changes or remove the API.

[ArtificialOwl]

A dedicated namespace means you have to change your app once the API switches from testing to stable. Would it be possible to put the APIs into the OCP namespace but tag them as @experimental or similar? Experimental could mean that the
API exists for that release but there are no guarantees for stability. Future versions might have a changes or remove the API.

While this helps a lot to not have to rename when switching to final, I am myself not a huge fan to have an API in public/ that is set as experimental using only PHPDoc. I also think it loosen the concept of lib/public/
From my point of view, this solution does not fully communicate any developer that he/she is using an experimental API. The fact that a developer import a lib from a testing namespace helps embrace the current status of the API.

[provokateurin]

For this to be successful there should be a limit on how long an API can stay in OCT before it moves to OCP. If it is there for more than 1 major server version, it will become impossible to maintain apps that need to support 2+ versions of the API.
Therefore I suggest that any API in OCT can only stay there for 1 major server release and then either has to be removed from OCT and redone or moved to OCP (with changes allowed).
If we can not make this guarantee, then I see no benefit over having it in OC as long as needed and then moving it to OCP.

[ArtificialOwl]

For this to be successful there should be a limit on how long an API can stay in OCT before it moves to OCP. If it is there for more than 1 major server version, it will become impossible to maintain apps that need to support 2+ versions of the API. Therefore I suggest that any API in OCT can only stay there for 1 major server release and then either has to be removed from OCT and redone or moved to OCP (with changes allowed). If we can not make this guarantee, then I see no benefit over having it in OC as long as needed and then moving it to OCP.

Totally agree, we need to set a maximum number of version to stay in that namespace.
I would prefer 2 myself but it is true that more will only makes everything harder to maintain. 1 should be good enough.

[provokateurin]

It would be great do write down this rule (and possibly others) in the docs or server wiki, just so that everyone is on the same page.

[provokateurin]

Also if you don't mind I suggest we apply strong psalm and rector rules to the namespace, so that any new API will be in great shape before it lands in OCP (at least if it goes through NCT first).

[ArtificialOwl]

wip documentation: nextcloud/documentation#12329

[susnux]

🚀