From 4e225a6801808b3482dc1e2149192f5ddf1d85e6 Mon Sep 17 00:00:00 2001 From: Thomas Steur Date: Thu, 8 Sep 2022 11:06:57 +1200 Subject: [PATCH 1/3] Minor update for deprecating api methods --- docs/4.x/apis.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/4.x/apis.md b/docs/4.x/apis.md index ca86c5517..74344b18e 100644 --- a/docs/4.x/apis.md +++ b/docs/4.x/apis.md @@ -54,20 +54,23 @@ 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. ## Developer changelog From 45574fef58dc2c317017ab296e8a2d143008854d Mon Sep 17 00:00:00 2001 From: Thomas Steur Date: Thu, 8 Sep 2022 11:16:53 +1200 Subject: [PATCH 2/3] Update release-management.md --- docs/release-management.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/release-management.md b/docs/release-management.md index 5218e2f36..151749b34 100644 --- a/docs/release-management.md +++ b/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. From 9a5b96eda5aed74d3422025e88bfac816ccd4569 Mon Sep 17 00:00:00 2001 From: Thomas Steur Date: Thu, 8 Sep 2022 11:19:57 +1200 Subject: [PATCH 3/3] Update apis.md --- docs/4.x/apis.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/4.x/apis.md b/docs/4.x/apis.md index 74344b18e..e85592a6e 100644 --- a/docs/4.x/apis.md +++ b/docs/4.x/apis.md @@ -72,6 +72,8 @@ Assuming we completely remove the deprecated API in the next major version, then 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 When we are adding a new API or when we are breaking or deprecating an existing API, then we change our [Developer Changelog](https://github.com/matomo-org/matomo/blob/4.x-dev/CHANGELOG.md). We also mention library updates and on occasion internal changes that may be interesting for developers.