Content: Blog


django CMS 4 is just around the corner – what happens to my existing django CMS 3 projects?

Fabian Braun

Dec. 26, 2023

Django CMS 4.1 takes the django CMS to the next level. After 15 years of history, django CMS reinvented itself. Due to some structural improvements, an automatic update of an existing project is not possible. Find out how to handle your existing django CMS 3 project. 

Navigating the Transition: Django CMS 3 to Django CMS 4

In the dynamic landscape of web development, staying updated with the latest technologies and frameworks is crucial. Django CMS, a powerful content management system built on Django, has seen significant advancements over the years, with Django CMS 4 being the latest milestone just around the corner. For those who have invested time and effort into Django CMS 3 projects, the advent of version 4 raises pertinent questions about the fate of their existing endeavours.

The Evolution to Django CMS 4

Django CMS 4 arrives with promising enhancements, offering improved performance, new integration capabilities, and a host of new features such as django CMS Versioning. However, its introduction doesn't render Django CMS 3 projects obsolete overnight. Understanding the implications and options during this transition period is vital for those with ongoing Django CMS 3-based websites.

No Automatic Migration: What Does It Mean?

Due to the substantial changes in django CMS' core, just running migration scripts will not suffice to upgrade a project. Besides migrating data, your project code might need some changes. The reason is that with django CMS 4, some key data structures have changed:

  1. django CMS' plugin tree has been fully rewritten using a new, highly performant data structure,
  2. placeholder fields have been replaced by placeholder relation fields,
  3. static placeholder by static aliases, and
  4. page publication has been removed from the core to allow for the more powerful capabilities of django CMS Versioning

Therefore, there is no automatic migration path from Django CMS 3 to 4. This places the responsibility squarely on developers and project owners to evaluate their options carefully.

Supported Until April 2026: A Breathing Space

The Django CMS community understands the significance of this migration phase. To ease concerns, support for Django CMS 3.11 projects is assured until April 2026 by our long-term support policy for bug and security fixes. This means existing projects won't abruptly lose support, providing a reasonable window for the transition: You are safe with django CMS 3.11.

We recommend to pin your requirements to django-cms<4 for all django CMS 3.11.x projects.

Navigating the Transition: Best Practices

The Assisted Migration Path: A Proposition Which We Will Build On

While an assisted migration path exists, for now, it comes with a disclaimer: "Use at Your Own Risk." This cautious warning underscores the complexities involved in migrating from Django CMS 3 to 4. It's imperative to weigh the benefits against the potential risks and complexities before proceeding with this route. Over time, we expect this path to become stable and reliable.

Assess the Project's Needs

Begin by conducting a comprehensive evaluation of your Django CMS 3 project for both the code and the databases. Consider factors such as the complexity of the project, the importance of new features in Django CMS 4, and the long-term goals for your website. Check which of the apps required by the project already support django CMS 4.

Plan and Strategize

Develop a migration plan that aligns with your project's specific requirements. This may involve identifying critical functionalities, prioritizing components for migration, and outlining a phased approach to minimize disruptions.

Fork the djangocms-4-migration tool

Andrew Aikman has created a tool to support the migration of data: djangocms-4-migration. Please note that Andrew provides this tool as a service only – there is no official support. If you need support, go to our #support channel on Slack. Make necessary adjustments to your fork of the tool to tailor it to your needs.

Seek Professional Guidance

Given the intricacies of the migration process, seeking assistance from experienced developers or agencies familiar with django CMS can be immensely beneficial. Their expertise can streamline the transition and mitigate potential risks.

Test Thoroughly

Before executing the migration, invest ample time in testing. Set up a separate environment to perform tests and simulations, ensuring that the migrated components function as intended without compromising the integrity of your website.

Back Up and Proceed with Caution

Before initiating any migration procedures, ensure robust backups of your Django CMS 3 project. This serves as a safety net, allowing you to revert to the previous state in case of unforeseen issues during the migration process.

To protect your data, django CMS 4 will not run any migrations unless a special setting – CMS_CONFIRM_VERSION4 –  is present and set to true. Setting it, indicates you know what you are doing. Just running migrations, with the setting activated but without other precautions, may result in data loss. 

Give feedback

Please share your stories, any road-blocks you hit, any extensions you needed to make your migration a success. This will help others with their migrations process. Also, it will help us to improve the support of migration efforts.

Conclusion: Embracing the Future

The transition from Django CMS 3 to 4 signifies progress and innovation within the django CMS ecosystem. While the absence of an automatic migration path presents challenges, it also offers an opportunity for a deliberate and strategic shift towards a more advanced platform.

With support available until April 2026 and cautionary guidance regarding assisted migrations, developers and project owners can navigate this transition period thoughtfully. By employing best practices, seeking guidance when needed, and conducting meticulous testing, the migration to Django CMS 4 can pave the way for enhanced performance, security, and a feature-rich environment for your web projects.

Remember, while the road ahead might seem daunting, it also holds the promise of a more robust and efficient framework for your web endeavours. Embrace the transition as an opportunity to evolve and leverage the latest advancements offered by Django CMS 4.

blog comments powered by Disqus

Do you want to test django CMS?

Try django CMS