All You Need to Know Before You Start Upgrading Your Sitefinity Projects

Introduction

With the release of Sitefinity 15, many organizations are contemplating an upgrade to leverage the latest features and improvements. Upgrading your Sitefinity project can be a significant task, and understanding the process is crucial for a smooth transition. This blog post outlines the key steps, considerations, and best practices for upgrading Sitefinity projects, especially when moving from one major version to another.

Preparing for the Upgrade

The upgrade process, whether for a major or minor version, starts with a bit of homework. Since Sitefinity is continuously evolving, some of the existing functionalities change and some of them get deprecated in newer versions. It is paramount to review release notes, API changes and deprecation notices for all the the major releases between the version you are on and the version you are upgrading to. This will give you insights on how the upgrade will affect your project's existing functionalities and whether you will need to plan additional time to rework some of your customizations or processes after the upgrade. You can check deprecated capabilities and API changes at the official Sitefinity documentation (Deprecated Capabilities and API Changes).

The second important aspect of the preparation is to devise a testing strategy - how the upgrade will be validated. The ideal scenario is having a rich set of automated tests that can guarantee the health of the system to a high degree. The alternative is having a checklist of test cases to be verified manually after the upgrade. If neither is present then creating a blueprint of what will be tested is a good way to start. What is also beneficial is if you know the health of the system before the upgrade. What is often the case is that projects undergo heavy testing after an upgrade and lots of bugs are attributed to it. It then turns out that the majority of the bugs were present even before the upgrade. This is why when bugs are logged during testing, a best practice is to check each bug on the old version and mark which ones are caused by the upgrade and which are not. Otherwise the upgrade turns out to a full regression testing and bug fixing process of the system which is often expensive and time consuming.

Upgrade Steps

Now let's review a sample process of how a Sitefinity project is upgraded.

1. Backup DB and Files: Always start by backing up your current database and files.

2. Development Environment: Begin the upgrade in a development environment and make sure there are no connection strings pointing to a production database.

3. Ensure the project is ready for upgrade: Ensure your project has the Sitefinity NuGet packages installed. If it was set up using the “Project Manager,” you’ll need to install the current version of the NuGet packages since as of Sitefinity 15, the "Project Manager" is no longer supported.

4. Use Sitefinity CLI for Upgrade: Utilize the Sitefinity CLI to upgrade the NuGet packages and apply other necessary changes such as fixing binding redirects and setting correct framework version. Details on how to install the Sitefinity CLI and how to run the upgrade commands can be found in the Sitefinity documentation.

5. Rebuild and Fix Custom Code: Rebuild your solution and address any issues arising from API changes.

6. Upgrade Sitefinity Admin App Extensions: If you have any admin app extensions, update the referenced Sitefinity SDK packages to the latest version. This is usually not mandatory since the extensions API is backward compatible, but is a best practice to do so.

7. Run Upgraded Code: Execute the upgraded code against the development database by running the site to trigger the upgrade scripts. This will upgrade the database and the Siefinity configuration files.

8. Update License: When the upgrade completes, you will be prompted to update your license file which is stored in “/App_Data/Sitefinity” folder.

9. Push changes to source control: - After the system notifies that the upgrade is successful, push all code changes including the Sitefinity configurations stored in the file system and the updated license to the source control.

10. Testing on development: Conduct smoke tests in the development environment to verify that there are no major issues.

11. Testing on QA/SIT environment: Deploy the source code changes along with the configuration changes and the license to an upper environment (usually SIT - System Integration Testing, or QA - Quality Assurance environment). When the site starts for the first time the SIT/QA database will also undergo upgrade. After it finishes the execution of the testing strategy can begin - automated tests, checklists, etc. Any upgrade bugs that are found get fixed on development and deployed to SIT/QA. The process repeats until no blocking bugs are present.

12. Deploy to production: After you have the confidence of the stability of the upgrade it is time to deploy to production. It is best to perform the deployment outside of peak hours and also to be ready for an emergency rollback with a backup of old files and database. Before starting check the following resources provided by Sitefinity on how to upgrade Sitefinity in an NLB environment in order to avoid downtime: KB Article, Documentation.

Upgrade Timeline and Team Composition

An upgrade can take anywhere from a couple of days to a couple of months. It depends on the project size, the amount of custom code, the functionalities that need to be tested, the presence of automated tests and the stability of the new Sitefinity version. A typical team might include one developer for the initial upgrade, additional developers for bug fixing or customization, 1-3 QAs for testing and issue logging, and a system/network administrator or DevOps engineer for deployment and backup management.

Key Risks and Concerns

1. New Version Bugs: Bugs in the new Sitefinity version can delay the upgrade process.

2. Repetitive Patch Upgrades: Sitefinity bug fixes in patches may require multiple upgrade cycles.

3. Issues in Production: Insufficient testing can lead to issues in the production environment.

4. Upgrade Process Blocking Work: The upgrade can interrupt other development activities or content releases.

5. Unexpected API Changes: These changes can break custom functionalities.

6. Downtime and Content Freeze: The upgrade can cause potential downtime and necessitate a content freeze on the production environment.

Mitigation Strategies

To mitigate these risks, first it is a good idea to dedicate enough time for the upgrade process so any unforeseen circumstances can be handled without much turbulence. Having a dedicated upgrade environment for running tests and validating the upgraded project can solve the issue with blocking other development activities and releases. To mitigate the risk of downtime, first start with creating a clear plan on how the upgrade will be deployed on the production environment and how it will be rolled back if anything went wrong and then test it out in a lower environment that closely resembles the setup of the production one.

Conclusion

Upgrading your Sitefinity project to the latest version ensures you benefit from enhanced security, performance, and features. While the process can be intricate, proper planning, testing, and adherence to the outlined steps can ensure a successful upgrade. Remember, staying updated with Sitefinity’s latest offerings is key to maintaining an efficient, secure, and high-performing website.