A Call for Stability and Backward Compatibility

Discussions
1

Hello :wave:

I’ve been a part of this community for four years, consistently working with Strapi, and as we approach the release of version V5, I feel compelled to express some concerns regarding the frequent breaking changes and the challenges they introduce.

Historically, the transition from V3 to V4 was taxing, and it seems V5 is poised to continue this trend. It’s concerning to see essential functions like findOne evolve so drastically over just four years:

  • V3: strapi.query('restaurant').findOne(params, populate);
  • V4: strapi.entityService.findOne(uid: string, id: ID, parameters: Params)
  • V5: await strapi.documents('api:restaurant.restaurant').findOne({documentId: 'a1b2c3d4e5f6g7h8i9j0klm'})

Other examples:

  • The infamous json response from V4
  • The upcoming documentId thing coming on V5
  • The V3 Services changed to V4 Entities changed to V5 Documents

Such changes require significant rewrites not just on the backend but also on the frontend, affecting every component that interacts with these APIs. This places a heavy burden on teams to continually adapt, diverting resources from feature development to maintenance.

Comparatively, communities like Laravel and technologies like SQLite offer extensive backward compatibility, ensuring that applications can be upgraded without requiring complete overhauls—this is not the case with Strapi.

The ideal approach would be to ensure backward compatibility. For example, maintaining the existing findOne method from V4 and introducing new functionality under a different name like findById. This would allow existing projects to continue functioning while offering pathways to adopt new features at a manageable pace.

Our team has decided to delay the migration to V5 until at least mid-2025. We appreciate the advancements each new version brings but wish these could be integrated without such significant disruption.

We understand the immense effort that goes into developing these versions and do recognize the potential benefits. However, a focus on backward compatibility could greatly alleviate the challenges faced by your user base

Thanks :pray:

3 Likes
2

Well spoken and 100% agree.

And you can add:

  • the localization-Array that just disappears with v5. Poof - and it’s gone.
  • Lifecycles (huge pain migrating from v3 to v4) now also again get a small change: Poof - and they are middlewares now.

It’s really frustrating that on one hand your presentations, blog-posts and announcements are full of promises (easy migration, migration-tool, not again that pain like v4) and how easy things are however if you have a look into it as developer: most of it is not true or not true yet.

I wanted to migrate 1-2 plugins that some customers use quite fast after the v5 go-live however if I read something like this:

on the end of august and maybe roughly 1? or 2? months before estimated release: I am shocked.

Investing time and resources to develop plugin(s) for the marketplace and getting smashed with a wooden hammer each major release: Meh.

2 Likes
3

Full agreement!

2 Likes
4

Thank you for sharing your feedback and concerns about Strapi and our move to Strapi 5. I understand the frustrations surrounding breaking changes during major migrations, especially when they may impact your project’s backend or frontend.

We learned from the Strpai v3 to v4 migration and are working hard to simplify this process. With our improved migration tool and backward compatibility API response flag, you can return your Strapi 5 data in the Strapi 4 responses format. That way, you can migrate your project incrementally instead of simultaneously focusing on both your front and backend.

However, we also want to focus on making Strapi 5 the best headless CMS possible. With new features come new requirements, which involve breaking changes.

We aim to mitigate this as much as possible, but avoiding breaking changes altogether is impossible.

In regards to entityService, new API response, and Lifecycles:

Technically, the entityService is still there (it doesn’t work exactly like it used to, but it is very close). We did add some backward compatibility options (the v4 header for REST and the GraphQL v4 format option).

Lifecycles still exist, but docSrv middlewares are new. But you bring up many good points, and we need to be more transparent about why we are making specific internal changes.

We need to provide more context. Here are some questions that have come up:

  • Why did we need the documents system?
  • Why did we need to change the response format?
  • Why did lifecycles become less valuable?
  • Why is there no localization field anymore?
  • Why did we remove the helper plugin?
  • Why was there so many changes to the design system?
  • Why can’t they modify the admin panel anymore?

To our team internally, these questions may be clear and understood. Still, we need to do a better job of sharing these answers with the community.

We do that during our Community Calls when folks ask questions.

We need to dedicate more content around our product & engineering decisions in why and how we made them.

So we can provide more context around the change rather than say, hey, we did this.

Moving forward, we will continue to strive for more visibility around support, significant releases, and development from product and engineering perspectives.

In the past, most of our content has focused on using Strapi and introducing new features rather than on the necessary changes we were making from product and engineering perspectives, the benefits they bring, and how they align with our long-term vision.

This could help bridge the gap between our engineering decisions and user expectations.

Working at Strapi, I learned one thing: Everyone on our team is committed to making Strapi better.

Our goal is to find a balance that allows us to innovate while maintaining the trust and confidence of our community.

Thank you for sharing your thoughts and providing feedback. It means a lot to us. I know we are not perfect, but we believe in Strapi and want to see it continue to grow and improve.

Thank you to Pierre, Derrick, Alex, and many others for the internal discussion surrounding this feedback.

Feel free to add any additional comments or questions. I will continue to pass along your feedback.

5

Thanks for the reply @Paul_Brats . It’s clear the team is putting a ton of work into making Strapi better, and that’s truly appreciated.

Just to share where I’m coming from, I use Strapi more as a straightforward API tool rather than a full CMS. I’ve always seen it as an all-in-one backend solution like what you’d get with ExpressJS. Because of that, the frequent big changes and new features haven’t really benefited my projects, especially since I don’t use many of the CMS features like Draft and Publish or the I18n stuff.

I’m wondering if something like NestJS or Fastify might be a better fit for me.

With that said, I still believe that you are introducing too many breaking changes:

  • all of the Strapi blog posts will be outdated (I still regularly land on V3 articles that are useless)
  • The Strapi Marketplace will take a massive hit (my prediction is that V5 will never reach the number of plugins that V4 has)

Contrast this with Wordpress, where I managed to upgrade a website made in 2005 in about 10 minutes, without needing to change a single line of code.

I hope you consider the significant impact of these breaking changes, and I wish the best for V5.

Thanks for all your work :pray:

2 Likes
6

I have 5 projects using Strapi in production, and if I need to update all the code, I’ll be in serious trouble. It would be impossible for me to manage, which is why I’m now considering other headless CMS options, even though Strapi has been my favorite until now.

2 Likes
7

Technically the entityService is not still there because localized entries are not working anymore with the removal of the localization-Array?!
Technically you mark something as deprecated but change the behaviour and make it unusable: that’s not deprecated.

Yes.

I would assume that Strapi as product in its current stage (quite long beta, v4 as “we fixed some shit that we’ve messed up”-version) will only get new features, changes regarding security, performance, … .
And not: “Hey, let’s think about how we can change existing core functionalities - the community surely will appreciate that!”.

@Paul_Brats Is there a specific date/month currently planned for the release of v5?

1 Like
8

I fully agree with @lolafkok the entityService like this isn’t just a deprecation, it makes it unusable in its current form. How would I use it like before without the localization field?

Are there any updates on this topic?