diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_33.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_33.rst index 95641615d01..f3faef0690b 100644 --- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_33.rst +++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_33.rst @@ -2,142 +2,25 @@ Upgrade to Nextcloud 33 ======================= -Front-end changes ------------------ +info.xml requirements +--------------------- -Files API -^^^^^^^^^ - -Breaking changes in the Files API package -""""""""""""""""""""""""""""""""""""""""" - -The ``nextcloud/files`` library was updated to version v4.0.0 in Server. -This release includes breaking API changes, so you’ll need to update your code in time for Server 33. +Update info.xml to add Nextcloud 33 to the support range: -To improve developer experience, we’ve expanded the context object passed to file actions. -It now includes additional fields such as the current folder and the current file list. -Function signatures have also changed: Action handlers now use destructured parameters instead of positional array arguments. - -You can find the full changelog and migration details in the repository: `nextcloud-files (4.0.0 beta) `_. - -Sidebar -""""""" - -The files API was changed in this release to use the Node API (available since Nextcloud 27) instead of the legacy ``FileInfo`` API. -For this the way to register sidebar tabs and actions has changed. -The ``OCA.Files.Sidebar`` API was removed and replaced with a new sidebar API available from the `@nextcloud/files `_ package. - -To register sidebar tabs you now have to use the new API which is based on web components, -for more details please refer to the changelog of the ``@nextcloud/files`` package. - -If you used the Files sidebar within your app you have to now use your own sidebar using the ``NcAppSidebar`` component from the `@nextcloud/vue `_ package. - -Otherwise if you already use your own sidebar implementation in your app but rely on the Viewer app to open the sidebar using the ``OCA.Files.Sidebar`` API, -you now have to listen to the ``viewer:sidebar:open`` event-bus event from the Viewer app to open your sidebar. -So enable the **open sidebar** action within the viewer you have to set ``enabledSidebar`` -when opening the viewer to allow opening the sidebar from within the viewer and listen for the mentioned event. - -Profile app -^^^^^^^^^^^ - -To make the profile sections API framework agnostic, allowing us to migrate the profile app to Vue 3 -while still allow external apps to use Vue 2 based profile section, -the ``OCA.Core.ProfileSections`` API was replaced with ``OCA.Profile.ProfileSections`` -which uses custom web components instead of being based on Vue components. - -As of Nextcloud 33 the ``OCA.Profile.ProfileSections.registerSection`` method accepts -a section object in the following format: - -.. code-block:: typescript - - interface ProfileSection { - /** - * Unique identifier for the section - */ - id: string - /** - * The order in which the section should appear (lower numbers appear first) - */ - order: number - /** - * The custom element tag name to be used for this section - * - * The custom element must have been registered beforehand, - * and must have the a `user` property of type `string | undefined`. - * - * @see https://developer.mozilla.org/en-US/docs/Web/API/Web_components - */ - tagName: string - /** - * Static parameters to be passed to the custom web component - */ - params?: Record - } - - -Added APIs -^^^^^^^^^^ - -- ``OCA.Profile.ProfileSections`` was added as a framework agnostic replacement for ``OCA.Core.ProfileSections``. - See section about the profile app above. - -Changed APIs -^^^^^^^^^^^^ - -- TBD - -Deprecated APIs -^^^^^^^^^^^^^^^ - -- TBD - -Removed APIs -^^^^^^^^^^^^ - -- The global ``md5`` implementation is removed. It was deprecated since Nextcloud 20 and not used by Nextcloud anymore. - If you still need a ``md5`` implementation you can just use some external package like `crypto-browserify `_. -- ``OCP.WhatsNew`` was removed. -- ``OC.AppConfig`` was deprecated since Nextcloud 16 and was now removed. Instead use ``OCP.AppConfig``. -- The ``OC.Settings.UserSettings`` api was removed. -- The ``OC.SystemTags`` api was removed. If you need to get the list of system tags, - check `this merge request `_ for how to fetch the tags directly. -- ``OC.set`` and ``OC.get`` were removed. Both are deprecated since Nextcloud 19. - For ``get``, if really needed, use `lodash get `_. - And for ``set``, use `lodash set `_. -- ``OC.redirect`` and ``OC.reload`` were removed. Both were deprecated since Nextcloud 17. - To replace ``OC.redirect`` directly use ``window.location``. - To replace ``OC.reload`` directly use ``window.location.reload``. -- ``OC.fileIsBlacklisted`` was removed. It was deprecated since Nextcloud 18. - The replacement is to use ``validateFilename`` from the `@nextcloud/files `_ package. -- The deprecated host methods from `OC` were deprecated since Nextcloud 17 and are now removed - - - To replace ``OC.getHost`` use ``window.location.host``. - - To replace ``OC.getHostName`` use ``window.location.hostname``. - - To replace ``OC.getPort`` use ``window.location.port``. - - To replace ``OC.getProtocol`` use ``window.location.protocol``. - -- The ``OCA.Core.ProfileSections`` API was removed and replaced with the framework agnostic ``OCA.Profile.ProfileSections`` API. - See section about the profile app above. - -- The ``OCA.Files.Sidebar`` API is removed. - This was the last API using the legacy ``FileInfo`` API. - It is now replaced with the new Node based sidebar API available from the `@nextcloud/files `_ package. - -- The ``OCA.Sharing.ExternalLinkActions`` API was deprecated in Nextcloud 23 and is now removed. - It was replaced with ``OCA.Sharing.ExternalShareAction`` which now have a proper API by using ``registerSidebarAction`` from `@nextcloud/sharing `_ instead. - -Back-end changes ----------------- +.. code-block:: xml -Support for PHP 8.5 added -^^^^^^^^^^^^^^^^^^^^^^^^^ + + + + -See below section for option code changes in your app and dependency management +To allow installation on older versions too, just keep the previous min-version. -Support for PHP 8.1 removed -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +PHP version range +^^^^^^^^^^^^^^^^^ -In this release support for PHP 8.1 was removed. Follow the steps below to make your app compatible. +In this release support for PHP 8.1 was removed and 8.5 was added. See the `PHP 8.5 release page `_ +for important changes. Then follow the steps below to mark your app as compatible. 1. If ``appinfo/info.xml`` has a dependency specification for PHP, increase the ``min-version`` to 8.2. @@ -145,7 +28,6 @@ In this release support for PHP 8.1 was removed. Follow the steps below to make - @@ -161,70 +43,25 @@ In this release support for PHP 8.1 was removed. Follow the steps below to make 3. If you have :ref:`continuous integration ` set up, remove PHP 8.1 and add PHP 8.5 from the matrices of tests and linters. -Default user agent for outgoing requests changed -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Database snowflake IDS +^^^^^^^^^^^^^^^^^^^^^^ -Starting with this release, the default user agent for requests done by the instance was changed from ``Nextcloud Server Crawler`` to ``Nextcloud-Server-Crawler/X.Y.Z``, where ``X.Y.Z`` is the current server version. - -Snowflake IDS -^^^^^^^^^^^^^ - -The following tables are now using snowflake ids: +The following tables are now using :doc:`/digging_deeper/snowflake_ids`: - ``oc_previews`` - ``oc_jobs`` - ``oc_share_external`` -The API related to these tables are now using a string instead of a int. See Changed APIs section and :doc:`/digging_deeper/snowflake_ids`. - -Added Events -^^^^^^^^^^^^ +The API related to these tables are now using a string instead of a int: -- TBD +- The ``setId`` and ``getId`` methods of ``\OCP\BackgroundJob\IJob`` were changed to return/accept a string instead of an int. +- The ``removedById``, ``getById`` and ``getDetailsById`` methods of ``\OCP\BackgroundJob\IJobList`` are now taking a string instead of an int. +- The ``setObjectId`` and ``getObjectId`` methods of ``\OCP\Activity\IEvent`` were changed to return/accept a string in addition to an int. -Added APIs -^^^^^^^^^^ +Adjust your app so it works with the changed type. -- We now expose ``\OCP\DB\IResult::iterateAssociative``, ``\OCP\DB\IResult::iterateNumeric`` from doctrine/dbal. - These two methods returns iterators that can be directly used in a `foreach` to iterate over a SQL query result. - For example: - -.. code-block:: php - - $result = $qb->executeQuery(); - foreach ($result->iterateAssociative() as $row) { - $id = $row['id']; - } - $result->closeCursor(); - -- This version allows to expose some Nextcloud related metrics using OpenMetrics format. - You can add your own exporters by implementing ``\OCP\OpenMetrics\IMetricFamily`` interface. - See :doc:`/digging_deeper/openmetrics` for more information. - -- ``ImageToTextOpticalCharacterRecognition`` TaskProcessing task type was added - -- ``ISynchronousWatermarkingProvider`` TaskProcessing provider interface was added to allow synchronous processing providers to react to the boolean includeWatermark flag - -Changed APIs -^^^^^^^^^^^^ - -- The ``setId`` and ``getId`` methods of ``\OCP\BackgroundJob\IJob`` were changed to return/accept a string instead of an int. Same for ``\OCP\BackgroundJob\IJobList`` were some methods (``removedById``, ``getById`` and ``getDetailsById``) are now taking a string instead of an int. The string is suppose to be a snowflake id. -- The ``setObjectId`` and ``getObjectId`` methods of ``\OCP\Activity\IEvent`` were changed to return/accept a string in addition to an int. The string is suppose to be a snowflake id. -- The ``\OCP\TaskProcessing\Task`` class now has ``getIncludeWatermark`` and ``setIncludeWatermark`` methods for indicating whether the provider should add a watermark to the generated output. -- The TaskProcessing OCS API now also accepts the ``includeWatermark`` flag when scheduling tasks - -Deprecated APIs -^^^^^^^^^^^^^^^ - -- The ``\OCP\DB\IResult::fetch`` and ``\OCP\DB\IResult::fetchAll`` are soft-deprecated. Instead you can use - ``\OCP\DB\IResult::fetchAssociative``, ``\OCP\DB\IResult::fetchNumeric`` and ``\OCP\DB\IResult::fetchOne`` - as replacement for ``\OCP\DB\IResult::fetch``; and ``\OCP\DB\IResult::fetchAllAssociative``, - ``\OCP\DB\IResult::fetchAllNumeric`` and ``\OCP\DB\IResult::fetchFirstColumn`` as replacement for - ``\OCP\DB\IResult::fetchAll``. If you use rector, you can use the Nextcloud33 set, to automatically port - most of your code to the new methods. - -Removed APIs -^^^^^^^^^^^^ +Removed PHP APIs +^^^^^^^^^^^^^^^^ - The ``\OCP\BackgroundJob\IJob::execute`` method was deprecated since Nextcloud 25 and was now removed. Instead use the ``IJob::start`` method, available since Nextcloud 25. @@ -267,3 +104,110 @@ Should be replaced by the following code: - The ``WhatsNew`` feature was removed as such the ``OC\Updater\ChangesCheck`` class and related APIs. This also includes the ``whats_new`` database table and the ``WhatsNewController`` class which was serving the now removed ``/core/whatsnew`` endpoint. + + +Removed JavaScript APIs +^^^^^^^^^^^^^^^^^^^^^^^ + +- The global ``md5`` implementation is removed. It was deprecated since Nextcloud 20 and not used by Nextcloud anymore. + If you still need a ``md5`` implementation you can just use some external package like `crypto-browserify `_. +- ``OCP.WhatsNew`` was removed. +- ``OC.AppConfig`` was deprecated since Nextcloud 16 and was now removed. Instead use ``OCP.AppConfig``. +- The ``OC.Settings.UserSettings`` api was removed. +- The ``OC.SystemTags`` api was removed. If you need to get the list of system tags, + check `this merge request `_ for how to fetch the tags directly. +- ``OC.set`` and ``OC.get`` were removed. Both are deprecated since Nextcloud 19. + For ``get``, if really needed, use `lodash get `_. + And for ``set``, use `lodash set `_. +- ``OC.redirect`` and ``OC.reload`` were removed. Both were deprecated since Nextcloud 17. + To replace ``OC.redirect`` directly use ``window.location``. + To replace ``OC.reload`` directly use ``window.location.reload``. +- ``OC.fileIsBlacklisted`` was removed. It was deprecated since Nextcloud 18. + The replacement is to use ``validateFilename`` from the `@nextcloud/files `_ package. +- The deprecated host methods from `OC` were deprecated since Nextcloud 17 and are now removed + + - To replace ``OC.getHost`` use ``window.location.host``. + - To replace ``OC.getHostName`` use ``window.location.hostname``. + - To replace ``OC.getPort`` use ``window.location.port``. + - To replace ``OC.getProtocol`` use ``window.location.protocol``. + +- The ``OCA.Core.ProfileSections`` API was removed and replaced with the framework agnostic ``OCA.Profile.ProfileSections`` API. + See section about the profile app above. + +- The ``OCA.Files.Sidebar`` API is removed. + This was the last API using the legacy ``FileInfo`` API. + It is now replaced with the new Node based sidebar API available from the `@nextcloud/files `_ package. + +- The ``OCA.Sharing.ExternalLinkActions`` API was deprecated in Nextcloud 23 and is now removed. + It was replaced with ``OCA.Sharing.ExternalShareAction`` which now have a proper API by using ``registerSidebarAction`` from `@nextcloud/sharing `_ instead. + +Files API +^^^^^^^^^ + +The ``nextcloud/files`` library was updated to version v4.0.0 in Server. +This release includes breaking API changes, so you’ll need to update your code in time for Server 33. + +To improve developer experience, we’ve expanded the context object passed to file actions. +It now includes additional fields such as the current folder and the current file list. +Function signatures have also changed: Action handlers now use destructured parameters instead of positional array arguments. + +You can find the full changelog and migration details in the repository: `nextcloud-files (4.0.0 beta) `_. + +Files app sidebar integration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The files API was changed in this release to use the Node API (available since Nextcloud 27) instead of the legacy ``FileInfo`` API. +For this the way to register sidebar tabs and actions has changed. +The ``OCA.Files.Sidebar`` API was removed and replaced with a new sidebar API available from the `@nextcloud/files `_ package. + +To register sidebar tabs you now have to use the new API which is based on web components, +for more details please refer to the changelog of the ``@nextcloud/files`` package. + +If you used the Files sidebar within your app you have to now use your own sidebar using the ``NcAppSidebar`` component from the `@nextcloud/vue `_ package. + +Otherwise if you already use your own sidebar implementation in your app but rely on the Viewer app to open the sidebar using the ``OCA.Files.Sidebar`` API, +you now have to listen to the ``viewer:sidebar:open`` event-bus event from the Viewer app to open your sidebar. +So enable the **open sidebar** action within the viewer you have to set ``enabledSidebar`` +when opening the viewer to allow opening the sidebar from within the viewer and listen for the mentioned event. + +Profile app integration +^^^^^^^^^^^^^^^^^^^^^^^ + +To make the profile sections API framework agnostic, allowing us to migrate the profile app to Vue 3 +while still allow external apps to use Vue 2 based profile section, +the ``OCA.Core.ProfileSections`` API was replaced with ``OCA.Profile.ProfileSections`` +which uses custom web components instead of being based on Vue components. + +As of Nextcloud 33 the ``OCA.Profile.ProfileSections.registerSection`` method accepts +a section object in the following format: + +.. code-block:: typescript + + interface ProfileSection { + /** + * Unique identifier for the section + */ + id: string + /** + * The order in which the section should appear (lower numbers appear first) + */ + order: number + /** + * The custom element tag name to be used for this section + * + * The custom element must have been registered beforehand, + * and must have the a `user` property of type `string | undefined`. + * + * @see https://developer.mozilla.org/en-US/docs/Web/API/Web_components + */ + tagName: string + /** + * Static parameters to be passed to the custom web component + */ + params?: Record + } + +Default user agent for outgoing requests changed +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Starting with this release, the default user agent for requests done by the instance was changed from ``Nextcloud Server Crawler`` to ``Nextcloud-Server-Crawler/X.Y.Z``, where ``X.Y.Z`` is the current server version. 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/release_notes/deprecations.rst b/developer_manual/release_notes/deprecations.rst new file mode 100644 index 00000000000..faaec3f45ab --- /dev/null +++ b/developer_manual/release_notes/deprecations.rst @@ -0,0 +1,18 @@ +============ +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. + +Database result fetching +------------------------ + +The ``\OCP\DB\IResult::fetch`` and ``\OCP\DB\IResult::fetchAll`` are soft-deprecated. Instead you can use +``\OCP\DB\IResult::fetchAssociative``, ``\OCP\DB\IResult::fetchNumeric`` and ``\OCP\DB\IResult::fetchOne`` +as replacement for ``\OCP\DB\IResult::fetch``; and ``\OCP\DB\IResult::fetchAllAssociative``, +``\OCP\DB\IResult::fetchAllNumeric`` and ``\OCP\DB\IResult::fetchFirstColumn`` as replacement for +``\OCP\DB\IResult::fetchAll``. diff --git a/developer_manual/release_notes/index.rst b/developer_manual/release_notes/index.rst new file mode 100644 index 00000000000..bc812874fc9 --- /dev/null +++ b/developer_manual/release_notes/index.rst @@ -0,0 +1,9 @@ +============= +Release notes +============= + +.. toctree:: + :maxdepth: 3 + + new + deprecations diff --git a/developer_manual/release_notes/new.rst b/developer_manual/release_notes/new.rst new file mode 100644 index 00000000000..4092c0392db --- /dev/null +++ b/developer_manual/release_notes/new.rst @@ -0,0 +1,11 @@ +=================== +New in this release +=================== + +This pages covers new features of the platform. + +Task processing watermarks +-------------------------- + +- The ``\OCP\TaskProcessing\Task`` class now has ``getIncludeWatermark`` and ``setIncludeWatermark`` methods for indicating whether the provider should add a watermark to the generated output. +- The TaskProcessing OCS API now also accepts the ``includeWatermark`` flag when scheduling tasks \ No newline at end of file