How to update from one version to another (2018.10 -> 2022.10)?

danielsiepmann · Post by **danielsiepmann** » 12 Jun 2023, 06:58

Hi everyone,

I'm completely new to Aimeos, and we got a TYPO3 installation with 2018.10 which we upgrade to 2022.10 right now.
I'm used to rector and changelogs of TYPO3 for upgrades, and I am wondering if I missed something regarding Aimeos.
I found the following sources:
- Changelogs like https://aimeos.org/docs/2022.x/changelog/2019.x/
- How to Upgrade https://aimeos.org/docs/2022.x/typo3/setup/#upgrade

The changelogs don't seem helpful to me as there is no documentation what needs to be done, only links to commits.
Also I couldn't find any automation like rector to auto migrate the code base.

The docs also doesn't seem to always match the actual situation. The project has custom templates and the docs don't point me to https://aimeos.org/docs/2022.x/develope ... #templates which seems necessary. Furthermore, it looks like it needs to be "template" instead of "templates".

I also encounter breaking changes due to renaming methods, e.g. getContext to context. I question whether those breaking changes are worth it?

Is that the expected developer experience during upgrades? I'm looking forward to any other helpful sources that ease the upgrade process, thanks in advance.

Post by **aimeos** » 12 Jun 2023, 08:48

danielsiepmann wrote: ↑12 Jun 2023, 06:58 The changelogs don't seem helpful to me as there is no documentation what needs to be done, only links to commits.
Also I couldn't find any automation like rector to auto migrate the code base.

Unfortunately, there are no automatic rules for upgrading but the links to the commits should help you to find out what has changed and if it affects your own code. If you haven't written the code and don't have any experience with Aimeos, then it's much harder for you compared to the original developer.

danielsiepmann wrote: ↑12 Jun 2023, 06:58 The docs also doesn't seem to always match the actual situation. The project has custom templates and the docs don't point me to https://aimeos.org/docs/2022.x/develope ... #templates which seems necessary. Furthermore, it looks like it needs to be "template" instead of "templates".

You are right, this is a mistake in the docs and now fixed.

danielsiepmann wrote: ↑12 Jun 2023, 06:58 I also encounter breaking changes due to renaming methods, e.g. getContext to context. I question whether those breaking changes are worth it?

Breaking changes with small improvements are always arguable but we've decided that we want of offer the best developer experience at the end. Also, renaming of methods was part of a larger context to simplify method names all over.

danielsiepmann · Post by **danielsiepmann** » 12 Jun 2023, 09:04

Thanks for your fast response.

aimeos wrote: ↑12 Jun 2023, 08:48 Unfortunately, there are no automatic rules for upgrading

I have not enough experience to start writing rector rules for migrating Aimeos code right now. Maybe I'll do more Aimeos upgrades in the future (I don't know that yet). I'll then will give it a try and share my experience with rector rules for Aimeos.

aimeos wrote: ↑12 Jun 2023, 08:48 You are right, this is a mistake in the docs and now fixed.

Thanks for the fast fix. I'll provide PRs for issues within the Docs I'll encounter.

aimeos wrote: ↑12 Jun 2023, 08:48 Breaking changes with small improvements are always arguable

Yes. It is frustrating if that's the first you encounter when working with Aimeos. It surely is different if you start a fresh project with Aimeos. Still I'm not sure if it is worth it until there are automated rules to migrate the code. But that's of course up to you. Just wanted to share my developer experience as a beginner confronted with the task of the update.

Help for Aimeos