feat(developermanual): move new and deprecated APIs to dedicated pages

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,29 +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.
-- ``\OCP\Talk\IConversationOptions`` has been extended, to allow defining the newly created conversation as related to a meeting with it's start and end date.
-  The information is used by Talk to automatically clean up such conversations after a given time.
-
-Changed APIs
-^^^^^^^^^^^^
-
-- ``\OCP\Notification\INotification::setIcon``, ``\OCP\Notification\INotification::setLink`` and ``\OCP\Notification\IAction::setLink`` now throw ``\OCP\Notification\InvalidValueException`` when the provided link is not absolute as previously announced in :doc:`./upgrade_to_30`
-
-Deprecated APIs
-^^^^^^^^^^^^^^^
-
-- TBD
-
 Removed APIs
 ^^^^^^^^^^^^
 

developer_manual/basics/storage/database.rst

@@ -1,3 +1,5 @@
+.. _database:
+
 ===============
 Database access
 ===============

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

developer_manual/prologue/compatibility_app_ecosystem.rst

@@ -20,15 +20,18 @@ 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 <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 <app-upgrade-guide>` section.
 
   The requirements for this documentation are:
 
   - It should be written so that app developers understand how to work around the change for their app in a tutorial format
   - 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
 --------------------------------

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 <https://packagist.org/packages/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.
+
+

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

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.