Minor update for deprecating api methods

docs/4.x/apis.md

@@ -54,20 +54,25 @@ Rarely, we may have to break an API for example for security reasons. We mention
 
 When we need to change an API, or remove an API, before removing or changing the API, we deprecate it:
 this can usually be done by adding `@deprecated` tag in the API, event name, etc.
-we announce the deprecation in the Developer Changelog at least 3-6 months early. With the deprecated annotation we also mention when it was deprecated (which Matomo version) and provide recommendations what to use instead.
+We announce the deprecation in the Developer Changelog at least 3-6 months early. With the deprecated annotation, we also mention when it was deprecated (which Matomo version) and provide recommendations of what to use instead.
 
 Example:
 
 ```php
 /**
- * @deprecated since Matomo 4.2.1. Use Xyz instead.
+ * @api 
+ * @deprecated since Matomo 4.2.1. Use {@link NewClass::newMethod()} instead.
  */
 public function getMyReport() {
 
 }
 ```
 
-When we release a new Major version (eg. Matomo 5.0.0) then we are will remove all `@deprecated` code and therefore break BC. We announce the details of code removed in the [developer changelog](/changelog) (see [instructions](#developer-changelog)) and we also document to developers how they can convert their code to the new way.
+Assuming we completely remove the deprecated API in the next major version, then we remove the `@deprecated` code and therefore break BC as part of the next new major version and not before that. We announce the details in the [developer changelog](/changelog) (see [instructions](#developer-changelog)) and we also document how developers can convert their code to the new way as part of a migration guide similar to [this example](https://developer.matomo.org/guides/migrate-matomo-3-to-4). 
+
+Sometimes, deprecated APIs may still be in the code base for many new major releases. In that case, we review before each major release if a deprecated method can be safely removed or not. If in doubt, we rather keep it for another major release.
+
+In most case, we should be able to remove the `@api` tag starting from the next major release so it no longer appears in the developer documentation. 
 
 ## Developer changelog
 

docs/release-management.md

@@ -82,10 +82,16 @@ Also, as soon as we start working on the next major version, we need to require
 * Update the [submodule github action](https://github.com/matomo-org/matomo/blob/4.x-dev/.github/workflows/submodules.yml), [composer update action](https://github.com/matomo-org/matomo/blob/4.x-dev/.github/workflows/composer-update.yml), and the [CLDR action](https://github.com/matomo-org/matomo/blob/4.x-dev/.github/workflows/update-intl.yml) to use the new main branch.
 * We can now start working and merging PRs for the next major release
   * We first start working on the big issues that take a very long to make sure they are finished by the time we want to release the first RC, and so they won't delay the release
+  * We look for all `@deprecated` APIs and review if we can remove the API now safely see also [Deprecating APIs](https://developer.matomo.org/guides/apis#deprecating-a-php-or-api-method). Removing an API now safely means
+    * The method or event is no longer in use by any of our own plugins or SDKs
+    * It won't break the upgrade process even if someone upgrades from an older version
+    * The removal of the API was mentioned in our migration guide for plugin developers and it can be expected that they migrate to the new way 
+    * It won't cause any issues for example with the Matomo Mobile app and the majority of other API consumers and we have given them plenty of time to migrate. Plenty of time may mean that we need to give them one major release cycle time to migrate as otherwise it could break things the moment they upgrade to Matomo when you can't have something working with the old and the new way at the same time.
   * We then start working on the issues that cause BC breaks, so we have plenty of time to adjust all the plugins, and also we indirectly test these changes sooner
   * The core team makes sure to communicate breaking changes to the plugins team so the plugins team can make the plugins compatible whenever there's a change. Sometimes the core team might also directly suggest PRs/changes to make a plugin compatible 
   * As always, we maintain the changelog for any breaking change
 
+
 #### api.matomo.org
 
 * In `config.ini.php` add two new release channels for this version. For example, when new major release is `5` as in `5.0.0` we need to add `path_latest_5x_stable` and `path_latest_5x_beta` release channels. We only need to add them for now, they can point to the same files as `latest_beta` (`LATEST_BETA`) and `latest_stable` (`LATEST`) for now. The Marketplace will use these release channels to check for latest available versions.