Skip to content

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

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

Open
ChristophWurst wants to merge 1 commit into
base: master
Choose a base branch
from
Open

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

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
42 changes: 6 additions & 36 deletions developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_34.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
^^^^^^^^^^^^

Expand Down Expand Up @@ -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
^^^^^^^^^^^^

Expand Down
2 changes: 2 additions & 0 deletions developer_manual/basics/storage/database.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _database:

===============
Database access
===============
Expand Down
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
7 changes: 5 additions & 2 deletions developer_manual/prologue/compatibility_app_ecosystem.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
--------------------------------
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 @@
.. _deprecated-apis:

============
Deprecations
Copy link
Copy Markdown
Member

@nickvergessen nickvergessen Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should also be a file per major for better linking?

Copy link
Copy Markdown
Member Author

@ChristophWurst ChristophWurst Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't like it. This will get messy quickly. It also makes it impossible to have a stable link as every major release will have the version embedded in the URL.

Copy link
Copy Markdown
Member Author

@ChristophWurst ChristophWurst Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could collect all current deprecations on this page. First we list the new ones, then there's the rest. When a deprecation is finally removed, it's also removed from the page.

It's equally messy, but there is one stable URL for the page.

Copy link
Copy Markdown
Member

@nickvergessen nickvergessen Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's also removed from the page.

Could have a second page then for those?

============

In order to improve our platform we are phasing out some APIs. Deprecated APIs are not removed before ???,
Copy link
Copy Markdown
Member

@nickvergessen nickvergessen Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

❓❓❓ lol

Copy link
Copy Markdown
Member Author

@ChristophWurst ChristophWurst Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right. That brings up the old discussion about what we promise as deprecation period. IIRC it was three years. Should I write it down or skip?

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.


14 changes: 14 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,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
23 changes: 23 additions & 0 deletions developer_manual/release_notes/new.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Loading