# Migrating from SpecSync v1 to v5 {% hint style="success" %} The licensing model of SpecSync allows you to use any versions, so it is recommended to always upgrade to the latest version. {% endhint %} {% hint style="info" %} SpecSync changed to use semantic versioning from v5 on. This means that the changes that earlier were minor version changes (e.g. v3.3 to v3.4) are now represented with major version changes. The version that follows v3.4 was earlier planned as v3.5 (or v1.4 in case of SpecSync for Jira) but promoted now to v5. {% endhint %} SpecSync for Azure DevOps v5 has introduced a couple of useful improvements but the features and the configuration is highly backwards compatible with the v3 releases, therefore the migration process is usually simple. You can find a complete list of improvements in the [Changelog](/specsync/jira/changelog.md#v5). To perform the version upgrade, please follow the steps below. ### Step 1: Verify compatibility Some older .NET versions are not supported anymore. Please note that the .NET version requirement is only about the .NET SDK installed in order to run SpecSync. The synchronize project can still target old .NET versions as well. If you cannot install a compatible .NET version to your systems where SpecSync is executed, we recommend using the SpecSync [binary installation](/specsync/jira/installation/native-binaries.md) or execute SpecSync from [Docker image](/specsync/jira/installation/docker-image.md). .NET versions not supported by v5 anymore: * .NET 3.1 * .NET 5 ### Step 2: Review breaking changes Besides the server versions or .NET frameworks that are not supported anymore, there are also a few minor breaking changes as well. These are partially related to removing features that have been marked deprecated earlier. The features that have been deprecated always provide a warning, so if your SpecSync v3.4 commands currently execute without warnings, these will not impact your usage. The remaining breaking changes do not impact the most of usages, but please review the complete list of [breaking changes](/specsync/jira/changelog.md#v5-breaking) ### Step 3: Learn about new concepts SpecSync v5 has introduced some new useful features and concepts. These are not mandatory to use, but they can improve your synchronization experience. For the best migration experience, we recommend learning about these new features before performing the upgrade. Some of the most important new concepts are: * [Remote scope concept](/specsync/jira/features/common-synchronization-features/remote-scope.md) that allows better control of which work items are synchronized and allows tracking work items that have been deleted from the source. The concept was used already in the previous versions, but in v5 there are more and better ways to utilize it. * [Configuration keys concept](/specsync/jira/features/common-synchronization-features/configuration-key.md) that can help to track which work items belong to which synchronization configuration in case you have multiple configurations synchronizing to the same project. * License keys provide a new way for using your SpecSync license. Instead of providing the license file, you can configure the license key in the configuration file or in an environment variable. Please check the [Licensing documentation](/specsync/jira/licensing.md#license-keys) for more details. ### Step 4: Upgrade SpecSync Upgrade SpecSync to the latest v5 version. Please check the [How to upgrade to a newer version of SpecSync](/specsync/jira/important-concepts/how-to-upgrade-specsync.md) guide for detailed steps. ### Step 5: Perform SpecSync upgrade command One of the new features of SpecSync v5 is the `upgrade` command. This command can be used to invoke the upgrade wizard that automatically fixes changes in the configuration file (e.g. for renamed configuration settings) and also prompts for configuring additional new features or configuration options. ``` dotnet specsync upgrade ``` The `upgrade` command only modifies the configuration file but it does not change anything in the Azure DevOps server. So you can perform the `upgrade` command safely and review the changes in the configuration file manually before performing a synchronization. {% hint style="info" %} You do not have to configure all optional feature with the `upgrade` command in one step. You can of course configure these features also manually by modifying the configuration file, but you can also re-run the `upgrade` command later to configure these. {% endhint %} ### Step 6: Review configuration changes and perform synchronization Once the `upgrade` command has been executed, you can review the changes of the configuration file. {% hint style="warning" %} The config file schema has changed from v3 to v5. This schema is used by the JSON editors, like Visual Studio Code, to provide auto-completion and validation. Some editors (notably Visual Studio) cache the schema information and show errors for the upgraded config file as they validate it with the old schema. Therefore, it is recommended to re-open the configuration file or even the whole editor after performing the `upgrade` command to ensure that the editor uses the latest schema. For Visual Studio, the "Reload Schemas" context menu command followed by a restart can also be used if the schema validation errors are still shown. {% endhint %} If the changes look good, you can perform a synchronization with the `push` command. It is recommended first to review the synchronization steps without actually changing the Azure DevOps server using the `--dryRun` option. ``` dotnet specsync push --dryRun ``` If the result is good, you can do the final synchronization with the `push` command. ``` dotnet specsync push ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.specsolutions.eu/specsync/jira/important-concepts/migrating-from-specsync-v3-to-v5.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.