From 7f1ed36eec4ee7d77c2d4fd11d30c5ef13ea8f54 Mon Sep 17 00:00:00 2001 From: Maxence Lange Date: Thu, 7 Nov 2024 19:22:45 -0100 Subject: [PATCH] NCU unstable namespace Signed-off-by: Maxence Lange --- developer_manual/digging_deeper/api.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/developer_manual/digging_deeper/api.rst b/developer_manual/digging_deeper/api.rst index ebe789e7115..3315720f5f0 100644 --- a/developer_manual/digging_deeper/api.rst +++ b/developer_manual/digging_deeper/api.rst @@ -7,3 +7,24 @@ PHP public API The public API is contained in the OCP namespace. See the `OCP API reference `_ for further details. + + +PHP unstable API +---------------- + +To avoid releasing incomplete public API, it is possible to release a +first version of the future API in the `NCU` namespace, following these rules: + +- Files are located in ``/lib/unstable/`` +- Code quality, comments, tests and psalm check are expected to be identical to the `OCP` namespace. +- Classes must be tag as ``@experimental``, including the current version of Nextcloud. +- Code from the `OCP` namespace must never mention anything coming from the `NCU` namespace. It can not require it as an argument, constant or return something from `NCU`. +- An API can only live in this unstable namespace for one major release. +- During this testing phase, the code and the API can be modified/restructured without limitation. +- API within the testing namespace must have up-to-date documentation. +- If accepted, the API will be copied to the `OCP` public namespace. +- Once tested, the version from the `NCU` namespace will be marked as deprecated. +- Deprecated API from the `NCU` namespace are kept for 2 major releases. + +.. note:: + - API from `NCU` are included to the ``nextcloud-deps/OCP`` package for easier testing with psalm