From ff021d4ab21195d4574f914adb1f04326dd84e04 Mon Sep 17 00:00:00 2001 From: Maxence Lange Date: Mon, 28 Oct 2024 18:01:21 -0100 Subject: [PATCH 1/6] NCT testing namespace --- developer_manual/digging_deeper/api.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/developer_manual/digging_deeper/api.rst b/developer_manual/digging_deeper/api.rst index ebe789e7115..2fc926bc472 100644 --- a/developer_manual/digging_deeper/api.rst +++ b/developer_manual/digging_deeper/api.rst @@ -7,3 +7,19 @@ PHP public API The public API is contained in the OCP namespace. See the `OCP API reference `_ for further details. + + +PHP testing API +--------------- + +To avoid releasing uncompleted public API, it is possible to release a +testing version of the future API in the NCT namespace, following those rules: + +- An API can only be nested in this testing namespace for 1 (one) major release, +- Once tested the API will be removed or copied to the OCP public namespace, +- If the API is not removed, the version from the NCT namespace will be marked as deprecated, +- Deprecated API from the NCT namespace are kept for 2 major releases, +- Code quality, comments, tests and psalm check are expected to be identical than in the OCP namespace. + +.. note:: + - API within the testing namespace might not have documentation other than in-code comments. From c553af589b2dcbf2a8574b54d7ee1d634689ca3c Mon Sep 17 00:00:00 2001 From: Maxence Lange Date: Tue, 29 Oct 2024 08:55:48 -0100 Subject: [PATCH 2/6] better phrasing Co-authored-by: Kate <26026535+provokateurin@users.noreply.github.com> Signed-off-by: Maxence Lange --- developer_manual/digging_deeper/api.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/developer_manual/digging_deeper/api.rst b/developer_manual/digging_deeper/api.rst index 2fc926bc472..4a2fe107224 100644 --- a/developer_manual/digging_deeper/api.rst +++ b/developer_manual/digging_deeper/api.rst @@ -12,14 +12,14 @@ The public API is contained in the OCP namespace. See the `OCP API reference PHP testing API --------------- -To avoid releasing uncompleted public API, it is possible to release a -testing version of the future API in the NCT namespace, following those rules: +To avoid releasing incomplete public API, it is possible to release a +testing version of the future API in the NCT namespace, following these rules: -- An API can only be nested in this testing namespace for 1 (one) major release, -- Once tested the API will be removed or copied to the OCP public namespace, +- An API can only live in this testing namespace for one major release, +- Once tested, the API will be removed entirely or moved to the OCP public namespace, - If the API is not removed, the version from the NCT namespace will be marked as deprecated, - Deprecated API from the NCT namespace are kept for 2 major releases, -- Code quality, comments, tests and psalm check are expected to be identical than in the OCP namespace. +- Code quality, comments, tests and psalm check are expected to be identical to the OCP namespace. .. note:: - API within the testing namespace might not have documentation other than in-code comments. From 93264dd84ae42812210556d6e9a048710036b170 Mon Sep 17 00:00:00 2001 From: Maxence Lange Date: Wed, 30 Oct 2024 11:04:22 -0100 Subject: [PATCH 3/6] adding @experimental to classes --- developer_manual/digging_deeper/api.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/developer_manual/digging_deeper/api.rst b/developer_manual/digging_deeper/api.rst index 4a2fe107224..0df5cb20391 100644 --- a/developer_manual/digging_deeper/api.rst +++ b/developer_manual/digging_deeper/api.rst @@ -15,11 +15,13 @@ PHP testing API To avoid releasing incomplete public API, it is possible to release a testing version of the future API in the NCT namespace, following these rules: -- An API can only live in this testing namespace for one major release, -- Once tested, the API will be removed entirely or moved to the OCP public namespace, -- If the API is not removed, the version from the NCT namespace will be marked as deprecated, -- Deprecated API from the NCT namespace are kept for 2 major releases, - 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. +- An API can only live in this testing namespace for one major release. +- During this testing phase, the code and the API can be modified/restructured without limitation. +- Once tested, the API will be removed entirely or copied to the OCP public namespace. +- If the API is not removed, the version from the NCT namespace will be marked as deprecated. +- Deprecated API from the NCT namespace are kept for 2 major releases. .. note:: - API within the testing namespace might not have documentation other than in-code comments. From 34e2e391e7542f43674473f079174c9d859da3bf Mon Sep 17 00:00:00 2001 From: Maxence Lange Date: Wed, 30 Oct 2024 11:26:22 -0100 Subject: [PATCH 4/6] some phrasing --- developer_manual/digging_deeper/api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/developer_manual/digging_deeper/api.rst b/developer_manual/digging_deeper/api.rst index 0df5cb20391..04759828d3f 100644 --- a/developer_manual/digging_deeper/api.rst +++ b/developer_manual/digging_deeper/api.rst @@ -19,8 +19,8 @@ testing version of the future API in the NCT namespace, following these rules: - Classes must be tag as `@experimental`, including the current version of Nextcloud. - An API can only live in this testing namespace for one major release. - During this testing phase, the code and the API can be modified/restructured without limitation. -- Once tested, the API will be removed entirely or copied to the OCP public namespace. -- If the API is not removed, the version from the NCT namespace will be marked as deprecated. +- If accepted, the API will be copied to the OCP public namespace. +- Once tested, the version from the NCT namespace will be marked as deprecated. - Deprecated API from the NCT namespace are kept for 2 major releases. .. note:: From b5e9d6c5b4b0f5400bf4fea09cbe6a79c5f5356b Mon Sep 17 00:00:00 2001 From: Maxence Lange Date: Wed, 6 Nov 2024 09:16:25 -0100 Subject: [PATCH 5/6] more details on NCT/ --- developer_manual/digging_deeper/api.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/developer_manual/digging_deeper/api.rst b/developer_manual/digging_deeper/api.rst index 04759828d3f..84992408fa0 100644 --- a/developer_manual/digging_deeper/api.rst +++ b/developer_manual/digging_deeper/api.rst @@ -13,15 +13,17 @@ PHP testing API --------------- To avoid releasing incomplete public API, it is possible to release a -testing version of the future API in the NCT namespace, following these rules: +testing version of the future API in the `NCT` namespace, following these rules: -- Code quality, comments, tests and psalm check are expected to be identical to the OCP namespace. +- 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 `NCT` namespace. It can not require it as an argument, constant or return something from `NCT`. - An API can only live in this testing namespace for one major release. - During this testing phase, the code and the API can be modified/restructured without limitation. -- If accepted, the API will be copied to the OCP public namespace. -- Once tested, the version from the NCT namespace will be marked as deprecated. -- Deprecated API from the NCT namespace are kept for 2 major releases. +- If accepted, the API will be copied to the `OCP` public namespace. +- Once tested, the version from the `NCT` namespace will be marked as deprecated. +- Deprecated API from the `NCT` namespace are kept for 2 major releases. .. note:: - API within the testing namespace might not have documentation other than in-code comments. + - API from `NCT` are included to the `nextcloud-deps/OCP` package for easier testing with psalm From ec1b2e327f6c5a00daa585fee09d9861efa516b9 Mon Sep 17 00:00:00 2001 From: Maxence Lange Date: Wed, 6 Nov 2024 10:13:26 -0100 Subject: [PATCH 6/6] enforcing documentation for tested API --- developer_manual/digging_deeper/api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer_manual/digging_deeper/api.rst b/developer_manual/digging_deeper/api.rst index 84992408fa0..98af5aa537e 100644 --- a/developer_manual/digging_deeper/api.rst +++ b/developer_manual/digging_deeper/api.rst @@ -20,10 +20,10 @@ testing version of the future API in the `NCT` namespace, following these rules: - Code from the `OCP` namespace must never mention anything coming from the `NCT` namespace. It can not require it as an argument, constant or return something from `NCT`. - An API can only live in this testing 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 `NCT` namespace will be marked as deprecated. - Deprecated API from the `NCT` namespace are kept for 2 major releases. .. note:: - - API within the testing namespace might not have documentation other than in-code comments. - API from `NCT` are included to the `nextcloud-deps/OCP` package for easier testing with psalm