Merge pull request #10261 from nextcloud/bugfix/noid/update-app-ecosy…

…stem-docs-with-new-process

feat(developer): Document the changes to the app ecosystem compatibility

developer_manual/app_publishing_maintenance/app_upgrade_guide/index.rst

@@ -2,6 +2,8 @@
 App upgrade guide
 =================
 
+.. _app-upgrade-guide:
+
 Once you've created and published the first version of your app, you will want to keep it up to date with the latest Nextcloud features.
 
 These sub pages will cover the most important changes in Nextcloud, as well as some guides on how to upgrade existing apps.

developer_manual/prologue/compatibility_app_ecosystem.rst

@@ -16,18 +16,15 @@ Documentation procedures of changes that affect app developers
 There are three procedures in place to facilitate communication to app developers about changes that affect them:
 
 
-1. The definition of done of a pull request includes documentation.
-This means the development of your pull request cannot be considered done if you introduced changes that affect app developers that you did not document.
+1. The definition of **Done** of a pull request includes documentation.
 
-.. TODO ON RELEASE: Change the link to the follow up issue
+  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 `Changes for developers and administrators issue <https://github.com/nextcloud/server/issues/34692>`_.
-The requirements for this documentation are:
+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.
+
+  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 documentation has to be carefully written. The author's name will be added to the final publication 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 immediately after merging the pull request.
-
-
-3. The documentation will then be copy-pasted into the developer documentation and on the forum for the first beta release.
+  - 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.