Hello there! I'm Mike Hardy and I work with Invertase to help maintain react-native-firebase. After reading this you will be able to handle react-native-firebase version upgrades with confidence.
First some history and some background:
react-native-firebase v5: v5 is so old you should upgrade immediately, and skip right to the "current versioning practices" section. v5 used One True Version so you have procrastinated long enough that what some think of as "history" is actually "things you ignored long enough you did not realize they happened", which might be the only benefit of still being on v5 😆
react-native-firebase v6: the early releases. These were "independently versioned" - that means the app package might get a release with a new version number but analytics (as an example) might now. This can work at a technical level but...which packages work with which? How do you communicate what version you are on? In practice, it's a mess.
firebase-android-sdk: our underlying library for Android, from the Google Firebase team. This project still uses independent versioning for each module, but has recently started providing a "Bill of Materials" (BoM) file with One True Version that lets you specify clearly what version of everything you have, with one number, for example "firebase-android-sdk v26.6.0"
firebase-ios-sdk: our underlying library for iOS, from the Google Firebase team. This project used to use independent versioning, but after receiving feedback from users, switched style to One True Version, so you may clearly specify your version with one number, for example "firebase-ios-sdk v7.7.0"
So that's the history of how things used to be (independent versions everywhere! What version am I on?? What version combination works together??), and where the underlying native iOS and Android SDKs are now (One True Version).
Current Versioning Practices:
For the react-native-firebase v10 release, we saw the firebase-ios-sdk switch to One True Version and agreed it was better. We changed our release policy such that every release will be unified, with all packages versioned with One True Version, with all release notes in one place. Now you always know what works together, you can easily communicate what version you are using, and you only have one place to check for release information. We hope you like the change!
How do we version releases?
Looking forward, how do we decide what kind of release to make? This is easy: we do our best to strictly follow semantic versioning release rules for version changes.
- Just bug fixes? It will be an x.x.N+1 release. Upgrade without a thought.
- New features, but everything is backwards-compatible? it will be an x.N+1.0 release. Make sure things work, but you should be able to adopt minor versions without much thought.
- If there is any sort of change that may cause build failures or behavior changes or similar, it will be a major version, an N+1.x.x release. Check the release notes!
You may have noticed that we are already on v11+. Another major version so soon? That is correct - we will not hesitate to release breaking changes, so the major versions will come fairly quickly, but they will always be as a major version so you will have a clear indication to pay attention.
How should you handle breaking changes in major versions?
Breaking change is an inevitable byproduct of progress, but we understand breaking changes may be frustrating. You already have enough to do, right? We will make sure you easily get the information you need to handle the upgrade.
We will make any breaking change release contain the exact action you must take, as part of the commit and the release notes in the CHANGELOG.
With that information, handling the version upgrade should be trivial.
Here's a screenshot where I have added red boxes to show how we communicate breaking changes from our v11.0.0 release:
You can see functions had a breaking change, you may trace it to the actual commit if you need to, and we clearly communicate that the possible break is that it now has higher minimum version requirements for firebase-ios-sdk and firebase-android-sdk. Now you know that if you have overridden your SDK versions from our defaults you will need to ensure they are compatible, or you will have to wait to adopt react-native-firebase v11, but either way the required action is clear.
That's it! One True Version.
- You know the modules will work together
- You can communicate what version(s) are in use easily all the way to native SDKs
- You know exactly where to go to handle breaking changes
Good luck with your projects!