A quick Introduction to the Backwards Compatibility Promise

It’s important to understand the backwards compatibility promise. Projects used by many applications can’t simply change behavior of features. Applications (and its developers) rely on stability of the framework. In short, Symfony’s promise is that your application should be able to upgrade from x.0 to x.4 without any code changing efforts.

Before releasing a new minor version (e.g. 5.3.0), the Symfony Core team needs to make sure 2 conditions are true:

• All changes to existing features are backwards compatible
• All new features must be stable.

The last point is important: Once a feature lands in a stable release, it’s no longer possible to change its behavior.

Now you know the main challenges Symfony is facing when releasing a new minor version, let’s see how you can help!

Reporting Issues during Stabilization

New features are often tested in little demo applications. As we all know, small demo applications often work much better than real life applications. This is why bugs and backwards compatibility breaks sometimes go completely unnoticed until real life applications start upgrading.

Receiving feedback from real life applications is crucial: Symfony’s only goal is to help you make real stuff in your daily jobs. It’s great to receive bug reports, at all times. Yet, it’s significantly more difficult to fix backwards compatibility breaks or bugs after a stable release.

Imagine there is a backwards compatibility break (BC break) that resulted in a PHP error. Applications that already upgraded fixed their code to remove this error. This means that removing the BC break is also a BC break in itself!

This is why testing pre-releases are critical. Pre-releases are not covered by the BC promise. If you find a problem, we can fix the break without yet another deprecation layer.

How to Test Pre-Releases

I hope by now, you understand the value of pre-release testing. But now, how do you do this? Is it really just 30 minutes?

Testing Pre-Releases in Applications

Most people maintain Symfony applications: private projects using the Symfony framework as a base. These projects can test pre-releases in 3 steps:

1. Update your composer.json to allow the next dev release. E.g. change 5.3.* to 5.4.*@dev for all symfony/* packages to test Symfony 5.4. Make sure to also update the extra.symfony.require key if it’s present
2. Add "minimum-stability": "dev" and "prefer-stable": true to your composer.json file. This tells Composer to install dev versions, but use stable versions for all your non-Symfony packages
3. Update your dependencies and run your test suite

Hopefully, your tests will pass. If they don’t, it means there is a BC break or bug in the upcoming release. In that case, you can report a bug to Symfony. It’s great to also provide a reproducer: some code that allows everyone to experience the bug you found. It’s hard to fix a bug if you don’t experience it ;)

There is also a great benefit for you: You already tested your application with the upcoming version. You may find yourself fixing some deprecations on a boring Friday afternoon. Before you know it, your applications is ready for the next release!

Testing Pre-Releases in Packages

Open source packages often test against multiple versions of their dependencies (e.g. they test support for Symfony 4 and 5).

You can also add a “dev” version to test your package with the next version of your dependencies. When running the dev tests, you can use composer config to allow dev dependencies:

1

composer config minimum-stability dev

This means your package now also tests against the dev dependencies. This is a great way to see if you support upcoming versions, as well as discovering bugs in your dependencies early. Depending on the stability of your dependencies, it can be a good idea to allow the dev tests to fail (e.g. using allow_failures in Travis CI).

I’ve used this technique in my own packages, which you can use as an example:

• GitHub Actions
• Travis CI

Take Homes

• Contributing to Symfony doesn’t only include writing code
• Bugs are much more easily fixed in a pre-release
• Please test pre-releases (of any software) and report issues you find