Skip to content

feat: split developer uprade docs #14180

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
ChristophWurst wants to merge 1 commit into
base: master
Choose a base branch
from
+169 −186
Draft

feat: split developer uprade docs #14180

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
316 changes: 130 additions & 186 deletions developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_33.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,150 +2,32 @@
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) <https://github.com/nextcloud-libraries/nextcloud-files>`_.

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 <https://www.npmjs.com/package/@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 <https://www.npmjs.com/package/@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<string, unknown>
}


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 <https://www.npmjs.com/package/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 <https://github.com/nextcloud/files_retention/pull/855>`_ 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 <https://lodash.com/docs#get>`_.
And for ``set``, use `lodash set <https://lodash.com/docs#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 <https://www.npmjs.com/package/@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 <https://www.npmjs.com/package/@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 <https://www.npmjs.com/package/@nextcloud/sharing>`_ instead.

Back-end changes
----------------
.. code-block:: xml

Support for PHP 8.5 added
^^^^^^^^^^^^^^^^^^^^^^^^^
<dependencies>
<php min-version="8.2" max-version="8.5" />
<nextcloud min-version="33" max-version="33" />
</dependencies>

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 <https://www.php.net/releases/8.5/en.php>`_
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.

.. code-block:: xml

<dependencies>
<php min-version="8.2" max-version="8.5" />
<nextcloud min-version="31" max-version="33" />
</dependencies>


Expand All @@ -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 <app-ci>` 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.
Expand Down Expand Up @@ -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 <https://www.npmjs.com/package/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 <https://github.com/nextcloud/files_retention/pull/855>`_ 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 <https://lodash.com/docs#get>`_.
And for ``set``, use `lodash set <https://lodash.com/docs#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 <https://www.npmjs.com/package/@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 <https://www.npmjs.com/package/@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 <https://www.npmjs.com/package/@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) <https://github.com/nextcloud-libraries/nextcloud-files>`_.

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 <https://www.npmjs.com/package/@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 <https://www.npmjs.com/package/@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<string, unknown>
}

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.
1 change: 1 addition & 0 deletions developer_manual/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ Table of contents
:maxdepth: 2

prologue/index
release_notes/index
getting_started/index
basics/index
app_development/index
Expand Down
18 changes: 18 additions & 0 deletions developer_manual/release_notes/deprecations.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <https://packagist.org/packages/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``.
9 changes: 9 additions & 0 deletions developer_manual/release_notes/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
=============
Release notes
=============

.. toctree::
:maxdepth: 3

new
deprecations
Loading