Mendix rolls out platform upgrades quite often. Some of them are minor fixes, while others change the way an application works in the background.
Teams that stay aligned get a more stable system, better performance, and access to improvements without rework, whereas teams that don’t, feel the disruption while development is still in progress.
In our project, we treated upgrades as a defined process. Each step was planned to control changes, reduce risk, and keep the mainline stable. Below are the best practices we follow to manage upgrades efficiently.
Create a Dedicated Feature Branch
Start the upgrade in its own feature branch, and not on the mainline.
Upgrades touch a lot like dependencies, marketplace modules, and custom logic. Mixing that with active feature development is how things might break.
A separate feature branch keeps all Mendix version changes contained. You can work through deprecated features, fix compatibility issues, and test changes without touching stable code.
It also gives the team room to figure things out. During upgrades, if there’s a gap between versions, you might face a setback where parts of the application don’t behave the same way. Keeping that work isolated makes it manageable.
What does this solve?
- Upgrade changes don’t collide with ongoing development.
- Mainline stays stable and production-ready.
- Teams can fix broken dependencies and module issues without pressure.
- Rolling back is straightforward if something goes wrong.
Perform the Upgrade Locally
Before you start the local upgrades, take a proper backup and go through the Mendix release notes. Pay attention to breaking changes, deprecated components, and anything that needs adjustment.
If there’s a large gap between versions, move step by step. It takes a bit longer, but avoids bigger setbacks later. Running the upgrade locally keeps the impact contained.
You can work through issues with marketplace modules, custom logic, or dependencies without affecting anyone else.
What does this solve?
- Issues stay limited to your local environment.
- Compatibility problems show up early, especially with modules and custom logic.
- Developers get time to debug and fix without pressure.
- Risk stays low before moving to shared environments.
Conduct Thorough Local Testing
When you’re testing it locally, check if the application runs without errors. Then move to core business logic and key user flows.
Focus on areas that tend to break, like custom widgets, third-party modules, and integrations. These aren’t always obvious, so take the time to go through them properly. It is best to catch issues in this stage because it saves time later.
What does this solve?
- Issues get identified early, both functional and technical.
- Core application stability is verified before deployment.
- Less rework later in the process.
- More confidence before moving to the next environment.
Handle complex testing with smarter automation
Explore Intelligent Automation
Deploy to Test Environment and Run Unit Testing
Now, take the upgraded feature branch to a test environment. Local setups won’t reflect everything, especially configurations tied to environments.
Run your unit tests. Go through integrations like REST APIs and external services. Watch the application logs closely.
Warnings and small errors show up here before they turn into bigger issues later. This step gives you a closer view of how the application will behave outside a developer machine.
What does this solve?
- Environment-specific configurations like endpoints and credentials are validated.
- Integrations are checked in a setup closer to real usage.
- Issues that don’t appear locally start to surface.
- You have a stable base before merging into Mainline.
Upgrade the Mainline
Next, you need to merge it into the mainline, and this step needs coordination. Other changes are usually in progress, and merging without alignment can create conflicts that are harder to fix later. Take the time to resolve conflicts properly and make sure the mainline stays stable after the upgrade.
At this point, the upgraded version becomes the base for everything that follows. If something is off here, it goes into User Acceptance Testing (UAT) and production.
What does this solve?
- Keeps a single source of truth for the application.
- Brings consistency across environments.
- Sets up the application for UAT and production.
- Reduces issues that come from delayed or messy merges.
Deploy to UAT and Run Regression Testing
Once the Mainline is upgraded, move it to the User Acceptance Testing (UAT) environment.
This is where the application is tested end to end. Regression testing matters here. You’re checking that what worked before still works now.
Bring in business users at this stage. They know where things tend to break and what actually matters in day-to-day use. Their feedback catches gaps that technical testing won’t.
What does this solve?
- Existing functionalities are verified across real workflows.
- Business use cases are tested in a realistic setup.
- Stakeholders get visibility and confidence before production.
Plan and Execute Production Deployment
If something breaks, you need a clear plan to revert without wasting time figuring it out on the spot. After deployment, keep a close watch on the application. Check logs, track performance, and look for anything that doesn’t behave as expected.
If earlier steps were handled properly, this should be controlled.
What does this solve?
- You have a rollback path if something goes wrong.
- Performance and stability are tracked from the start.
- End users get a stable experience after the upgrade.
Keep your mendix upgrades under control
Talk to an Expert
What to Do Next?
Start by listing everything your application depends on. Include marketplace modules, custom widgets, and integrations. Check each one against the target Mendix version.
Update what’s supported, replace what isn’t, and flag anything that needs rework. Fix these gaps as you find them instead of waiting for the upgrade to expose them.
