From d29254f3a8a2cf240a8a77b6a537604e3e8d912e Mon Sep 17 00:00:00 2001 From: Joas Schilling Date: Thu, 4 May 2023 08:50:19 +0200 Subject: [PATCH 1/2] feat(developer): Document the changes to the app ecosystem compatibility Signed-off-by: Joas Schilling --- .../app_upgrade_guide/index.rst | 2 ++ .../prologue/compatibility_app_ecosystem.rst | 17 ++++++++--------- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/index.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/index.rst index 65660dca8e3..7fbbde3aa98 100644 --- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/index.rst +++ b/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. diff --git a/developer_manual/prologue/compatibility_app_ecosystem.rst b/developer_manual/prologue/compatibility_app_ecosystem.rst index e6cb6d92294..4a186dedb0d 100644 --- a/developer_manual/prologue/compatibility_app_ecosystem.rst +++ b/developer_manual/prologue/compatibility_app_ecosystem.rst @@ -16,18 +16,17 @@ 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 `_. -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 ` 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. - + - 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. The documentation will then be copy-pasted into the developer documentation and on the forum for the first beta release. +3. The documentation will then be copy-pasted into the forum for the first beta release. From bce267455d93a66b5de2e6d2822192a76d8998b4 Mon Sep 17 00:00:00 2001 From: Joas Schilling Date: Thu, 4 May 2023 10:49:13 +0200 Subject: [PATCH 2/2] fix(develop): Fix suggestions Signed-off-by: Joas Schilling --- developer_manual/prologue/compatibility_app_ecosystem.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/developer_manual/prologue/compatibility_app_ecosystem.rst b/developer_manual/prologue/compatibility_app_ecosystem.rst index 4a186dedb0d..1c392779da4 100644 --- a/developer_manual/prologue/compatibility_app_ecosystem.rst +++ b/developer_manual/prologue/compatibility_app_ecosystem.rst @@ -18,7 +18,7 @@ There are three procedures in place to facilitate communication to app developer 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 (additions, removals or modifications) that affect app developers that you did not document. + 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 ` section. @@ -28,5 +28,3 @@ There are three procedures in place to facilitate communication to app developer - 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. The documentation will then be copy-pasted into the forum for the first beta release.