From 68b371012a38dda101cc470c6e60e1f7d8e77a53 Mon Sep 17 00:00:00 2001 From: Christoph Wurst <1374172+ChristophWurst@users.noreply.github.com> Date: Tue, 31 Mar 2026 16:40:27 +0200 Subject: [PATCH] feat(developermanual): move new and deprecated APIs to dedicated pages Signed-off-by: Christoph Wurst <1374172+ChristophWurst@users.noreply.github.com> --- .../app_upgrade_guide/upgrade_to_34.rst | 42 +++---------------- developer_manual/basics/storage/database.rst | 2 + developer_manual/index.rst | 1 + .../prologue/compatibility_app_ecosystem.rst | 7 +++- .../release_notes/deprecations.rst | 18 ++++++++ developer_manual/release_notes/index.rst | 14 +++++++ developer_manual/release_notes/new.rst | 23 ++++++++++ 7 files changed, 69 insertions(+), 38 deletions(-) create mode 100644 developer_manual/release_notes/deprecations.rst create mode 100644 developer_manual/release_notes/index.rst create mode 100644 developer_manual/release_notes/new.rst diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_34.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_34.rst index 5fd463b9d69..fcb71ec847d 100644 --- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_34.rst +++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_34.rst @@ -1,25 +1,16 @@ +.. _upgrade_to_34: + ======================= Upgrade to Nextcloud 34 ======================= +.. + Add one section for each change. + Only list changes absolutely necessary to keep an app running. Use the dedicated deprecation and new features pages for optional changes and announcements. + Front-end changes ----------------- -Added APIs -^^^^^^^^^^ - -- TBD - -Changed APIs -^^^^^^^^^^^^ - -- TBD - -Deprecated APIs -^^^^^^^^^^^^^^^ - -- TBD - Removed APIs ^^^^^^^^^^^^ @@ -47,27 +38,6 @@ Removed APIs Back-end changes ---------------- -Added Events -^^^^^^^^^^^^ - -- TBD - -Added APIs -^^^^^^^^^^ - -- ``\OCP\DB\QueryBuilder\ITypedQueryBuilder`` is added in favour of ``\OCP\DB\QueryBuilder\IQueryBuilder`` and can be accessed through ``\OCP\IDBConnection::getTypedQueryBuilder``. - This query builder has the benefit of accurately returning the selected columns in a query result, increasing type safety. - -Changed APIs -^^^^^^^^^^^^ - -- TBD - -Deprecated APIs -^^^^^^^^^^^^^^^ - -- TBD - Removed APIs ^^^^^^^^^^^^ diff --git a/developer_manual/basics/storage/database.rst b/developer_manual/basics/storage/database.rst index 01f909e0bd2..d1597316169 100644 --- a/developer_manual/basics/storage/database.rst +++ b/developer_manual/basics/storage/database.rst @@ -1,3 +1,5 @@ +.. _database: + =============== Database access =============== diff --git a/developer_manual/index.rst b/developer_manual/index.rst index 751723f1877..362a0d67432 100644 --- a/developer_manual/index.rst +++ b/developer_manual/index.rst @@ -15,6 +15,7 @@ Table of contents :maxdepth: 2 prologue/index + release_notes/index getting_started/index basics/index app_development/index diff --git a/developer_manual/prologue/compatibility_app_ecosystem.rst b/developer_manual/prologue/compatibility_app_ecosystem.rst index ba786a3bea5..47531988095 100644 --- a/developer_manual/prologue/compatibility_app_ecosystem.rst +++ b/developer_manual/prologue/compatibility_app_ecosystem.rst @@ -20,7 +20,7 @@ There are three procedures in place to facilitate communication to app developer This means the development of your pull request cannot be considered done if you introduced changes (additions, removals or modifications) that affect app developers that you did not document. -2. A change that affects app developers, has to be reported and documented by the author of the pull request in the :ref:`App Upgrade guide ` section. +2. A change necessary for app developers to execute for app compatibility in a new version, has to be reported and documented by the author of the pull request in the :ref:`App Upgrade guide ` section. The requirements for this documentation are: @@ -28,7 +28,10 @@ There are three procedures in place to facilitate communication to app developer - The steps should be explicitly written, so the documentation shall not rely upon links to external resources for the steps. While it is encouraged to add an external links as additional reference, it is a hard requirement that the documentation is readable and actionable without browsing to this link. - The change author's name should be added to the section so readers can reach out to the author if they have questions or if something is unclear. - Timeline: the documentation is required to be handed in when finalizing the pull request and should be merged timely close to the actual change. - + +3. New APIs are advertised at :ref:`new-apis` but need a dedicated documentation section. + +4. Deprecations are collected at :ref:`deprecated-apis`. Other documentation requirements -------------------------------- diff --git a/developer_manual/release_notes/deprecations.rst b/developer_manual/release_notes/deprecations.rst new file mode 100644 index 00000000000..07dec0f5e6c --- /dev/null +++ b/developer_manual/release_notes/deprecations.rst @@ -0,0 +1,18 @@ +.. _deprecated-apis: + +============ +Deprecations +============ + +In order to improve our platform we are phasing out some APIs. Deprecated APIs are not removed before ???, +unless the breakage can not be avoided. + +We highly recommend using the `Nextcloud Rector `_ +rules, which can fix some API changes automatically. + +.. + Add one section for each group of deprecations (e.g. group files api changes, authentication changes). + Also deprecate the feature at their dedicated documentation page. + After branch-off the contents below will be cleared. + + diff --git a/developer_manual/release_notes/index.rst b/developer_manual/release_notes/index.rst new file mode 100644 index 00000000000..9cb1067e443 --- /dev/null +++ b/developer_manual/release_notes/index.rst @@ -0,0 +1,14 @@ +============= +Release notes +============= + +This section is for developers and maintainers who are familiar with an earlier version of the documentation. + +Here we try to summarize what's new. You will find the breaking changes at :ref:`upgrade_to_34`, new deprecations at :ref:`deprecated-apis` and new API features at :ref:`new-apis`. + +.. toctree:: + :maxdepth: 3 + + new + deprecations + ../app_publishing_maintenance/app_upgrade_guide/upgrade_to_34 diff --git a/developer_manual/release_notes/new.rst b/developer_manual/release_notes/new.rst new file mode 100644 index 00000000000..b9c8eef658b --- /dev/null +++ b/developer_manual/release_notes/new.rst @@ -0,0 +1,23 @@ +.. _new-apis: + +=================== +New in this release +=================== + +This pages covers new features of the platform. + +.. + Add one section for each new feature. + Every feature should just have a brief description. Details have to be documented on a dedicated, persistent page. + After branch-off the contents below will be cleared. + +Typed query builder +------------------- + +``\OCP\DB\QueryBuilder\ITypedQueryBuilder`` was added in favour of ``\OCP\DB\QueryBuilder\IQueryBuilder`` and can be accessed through ``\OCP\IDBConnection::getTypedQueryBuilder``. + +This query builder has the benefit of accurately returning the selected columns in a query result, increasing type safety. + +.. todo:: This linked page does not have coverage for the new API. + +See :ref:`database` for details.