This article provides guideline for developers wanting to upgrade to a newer Unity version. I highlight things to be aware of and to try first before changing the Unity version of a given project.
Understanding Unity versions
For reference, Unity is versioned in this format: major.minor.patch + release
2021.2.3f1 => major: 2021, minor: 2, patch: 3, release: final 1
Note that release may have an a (alpha) or b (beta) too. You will want to avoid those for production projects.
Why Update Unity?
First: why do you intend to update Unity? Sometimes, developers do so based on hope alone. Don’t be that developer! 😉
Skip the next section if:
- you want to try out a new / improved Unity feature
- you have a specific issue that’s known (!) to have been fixed
Perform Due Diligence!
If you have unspecific issues, first analyze if the issue isn’t with your project’s code.
Seriously! Take your time, maybe an hour or so, I’ll wait …
You say the issue is not in your code? Damn. Okay, I’ll trust you don’t want to procrastinate on debugging and code analysis by jumping to a new Unity version based on a remote hope. 😉
Next, check any packages and 3rd party assets that could possibly cause issues. Your IDE’s Find in Files function fed with one or more fragments of the Console messages may help narrow it down. Also, try Find Usages of a given type mentioned in the logs.
What? Why? That’s not …
I know, I know! It’s not your code alright. But you put it in your project, so they are now your responsibility!
Now, are you certain to a reasonable degree that the issue isn’t with any of the packages or 3rd party assets? Alright, let’s move on.
Try deleting Library first!
For any “unusually odd issue” the first thing you should attempt is to delete the Library folder of the project.
This is such a common advice but worth mentioning because it’s still often overlooked because you never know when it is a good time to try that. Especially when it takes 20+ minutes to recreate the Library.
But yes, before upgrading Unity out of hope that it will fix an issue, deleting the Library folder can potentially save you a lot of time and headaches!
Caution: Be sure to have closed both Unity and your IDE before deleting the Library folder. Also be patient and wait for the delete operation to complete. This can sometimes be overlooked as you go on doing other stuff with the delete dialog being hidden by some other window.
With the Library deleted, re-open the project with the usual Unity version and check if the issue persists. If not, there you have it: it’s fixed! Otherwise, read on.
Runtime Issues
Is the issue with a particular build and device/platform/browser?
If so, try creating a new template project from the Unity Hub using the same Unity version that you use in your project. Does it have the same issue?
If not, copy your project’s ProjectSettings and Packages folders over to that project, build again and see if the issue occurs. If so, check your settings and packages instead rather than upgrading Unity.
You can take this even further and attempt to migrate some or all of your assets over or experiment with some of it in the new project to see if you can provoke and then narrow down the issue. This is for advanced users and goes beyond the scope of this article but it’s a noteworthy mention because it has been proven helpful to narrow down project-specific issues.
If the new project DOES have the same issue out of the box, try upgrading the new project to a newer Unity version instead of your production project until (hopefully) the issue goes away. Using the new project will be way faster than using your existing project because the new project will typically be smaller in size. Once you found a version that has the fix in it, you can upgrade your production project once to that specific version. You may still have to fix any API change issues and such though.
Using a new project will also help in reporting any bugs to Unity because you can make the repro steps pretty darn simple and reliable.
Preparing to Upgrade
You decided it’s time to upgrade but do go through that checklist to be sure of a few things:
- You have tried deleting the Library folder and re-opened the project to see if the issue went away. More often than not this fixes the bi-monthly “unusally odd issue”.
- You do NEVER upgrade your production project!
- Ideally your project is under source control and you are creating a branch for trying out new Unity versions.
- If not using source control: make a copy of the entire project folder first! If it takes a long time, create a new folder first and copy everything except for the Library folder. The Library consists of many small files which are slow to copy thus it may be faster to let Unity recreate it. You will also have to test EXTENSIVELY every feature and platform to find any odd issue caused by upgrading because once you throw away your existing version you have no way of going back! => Start using source control!
- CAUTION: Be sure you have closed all Unity and IDE instances before branching / copying!
- NEVER downgrade to an earlier Unity version!
- Downgrading a project to an earlier Unity version IS NOT SUPPORTED!
- Note: The fact that the project “still works” when ignoring this recommendation doesn’t mean it can’t cause havok later on, or that this always works without issues, or that any such issues will be obvious.
- Follow an upgrade strategy …
Upgrade strategies
You can follow two upgrade strategies: conservative or optimistic. Conservative is best applied for hunting down known fixes and upgrading projects that already have serious work put into them.
Conservative
Upgrade to the latest minor version first, ie when using 2021.2.3f1 upgrade to (for example) 2021.2.19f1 and test for any issues as well as whether the issue you had was fixed. If so, stick with that version.
If the issue persists, you know you won’t find a fix in this major version (2) and can move on to the next minor version (3).
Note that if you are DAMN SURE that this particular issue is fixed in a newer Unity version you should instead take the time and sift through the changelogs of each Unity version in order to find the version with that fix and go straight for that version. This can actually save you time considering the time it takes to upgrade or recreate the Library folder for complex projects.
If you have no idea whether this particular issue has been fixed by Unity, you can save time by taking the Optimistic strategy instead. Because if that doesn’t help, chances are the issue is with your project only.
Optimistic
The optimistic strategy has you upgrading straight to the latest tech stream release version, or slightly more conservative to the latest LTS release version.
For example, if the project is using 2021.2.3f1 you may either upgrade to 2022.3.14f1 (LTS) or 2023.1.7f1 (tech stream).
If your particular issue is fixed but you encounter other issues, try upgrading (don’t downgrade!!!) to the earliest minor version of this particular minor version.
What I mean by that using the above cases is: try either 2022.3.0f1 )(LTS) or 2023.1.0f1 (tech stream). Because if the new issues still persist you know that you will have to fix these yourself if you want to stay on this particular major+minor version. Typically those are caused by API changes, but also sometimes changes to the underlying tech such as mobile SDK versions or render pipelines.
Divide and Conquer
There is a third strategy used rarely. The conditions are that you want to upgrade to a higher minor version but the latest release of that minor version has a new nasty issue you wish to avoid.
Assuming you are on 2021.2.3f1 and the latest release of that minor version is 2021.2.15f1 but it breaks some Inspector GUI rendering or some other annoying issue but it does fix the original issue. In this case you divide and conquer (or sift through changelogs).
This means upgrading to half the patch version difference: ((15-3) / 2) + 3 = 9
Therefore, try upgrading from 2021.2.3f1 to 2021.2.9f1 first tocheck if the desired fix is in there but the annoying new issue isn’t.
Depending on that you can continue to either go for a higher version: ((15-9) / 2) + 9 = 12 which would be: 2021.2.12f1.
Alternatively, you would take your 2021.2.3f1 project and upgrade (remember to NEVER downgrade!) to the other side of the divide and conquer strategy: ((15-9) / 2) + 3 = 6 which would mean upgrading to 2021.2.6f1 instead.
Apply rounding as necessary.
This way you can more quickly narrow down a particular in-between version of Unity that has one particular issue fixed but doesn’t show another nasty new issue.
However, there is a chance that the fixed issue is in the same version as the newly introduced nasty issue. In that case you are either out of luck or may consider upgrading to a higher minor version, if possible.
Leave a Reply