diff --git a/README.md b/README.md index 3c728adc2..0b7562c5b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# Azure DevOps Migration Tools [![Chocolatey](https://img.shields.io/chocolatey/dt/vsts-sync-migrator.svg)](https://chocolatey.org/packages/vsts-sync-migrator/) [![GitHub release](https://img.shields.io/github/release/nkdAgility/vsts-sync-migration.svg)](https://github.com/nkdAgility/azure-devops-migration-tools/releases) ![Build on VSTS](https://nkdagility.visualstudio.com/_apis/public/build/definitions/1b52ce63-eccc-41c8-88f9-ae6ebeefdc63/94/badge) +# Azure DevOps Migration Tools [![GitHub release](https://img.shields.io/github/release/nkdAgility/vsts-sync-migration.svg)](https://github.com/nkdAgility/azure-devops-migration-tools/releases) ![Build on VSTS](https://nkdagility.visualstudio.com/_apis/public/build/definitions/1b52ce63-eccc-41c8-88f9-ae6ebeefdc63/94/badge) -The Azure DevOps Migration Tools allow you to bulk edit and migrate data between Team Projects on both Microsoft Team Foundation Server (TFS) and Azure DevOps Services. Take a look at the [documentation](https://nkdagility.com/docs/azure-devops-migration-tools/) to find out how. This project is published as [code on GitHub](https://github.com/nkdAgility/azure-devops-migration-tools/) as well as a [Azure DevOps Migration Tools on Chocolatey](https://chocolatey.org/packages/vsts-sync-migrator/). +The Azure DevOps Migration Tools allow you to bulk edit and migrate data between Team Projects on both Microsoft Team Foundation Server (TFS) and Azure DevOps Services. Take a look at the [documentation](https://nkdagility.com/docs/azure-devops-migration-tools/) to find out how. This project is published as [code on GitHub](https://github.com/nkdAgility/azure-devops-migration-tools/) as well as a Winget package a `nkdAgility.AzureDevOpsMigrationTools`. **Ask Questions on Github: https://github.com/nkdAgility/azure-devops-migration-tools/discussions** @@ -53,7 +53,14 @@ The Azure DevOps Migration Tools allow you to bulk edit and migrate data between - [Getting Started](https://nkdagility.com/learn/azure-devops-migration-tools/getting-started.html) - [Documentation](https://nkdagility.com/learn/azure-devops-migration-tools/) - [Questions on Usage](https://github.com/nkdAgility/azure-devops-migration-tools/discussions) - - [Bugs](https://github.com/nkdAgility/azure-devops-migration-tools) + +## Installing an running the tools + +We use [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/) to host the tools, and you can use the command `winget install nkdAgility.AzureDevOpsMigrationTools` to install them on Windows 10 and Windows 11. For other operating systems you can download the [latest release](https://github.com/nkdAgility/azure-devops-migration-tools/releases/latest) and unzip it to a folder of your choice. + +The tools will be installed to `%Localappdata%\Microsoft\WinGet\Packages\nkdAgility.AzureDevOpsMigrationTools_Microsoft.Winget.Source_XXXXXXXXXX` and a symbolic link to `devops-migration.exe` that lets you run it from anywhere using `devops-migration init`. + +For a more detailed getting started guide please see the [documentation](https://nkdagility.com/docs/azure-devops-migration-tools/getting-started.html). ## Support @@ -72,6 +79,7 @@ We use these tools with our customers, and for fun, to do real world migrations ## Change Log +- 14.0 - Move from Chocolaty to Winget as the base installer. We will continue to publish to Chocolaty, but we recommend using `winget install nkdAgility.AzureDevOpsMigrationTools` for future installs. Main executable renamed to "devops-migration.exe" to prevent conflict with other applications with symbolic links. - 13.2 - Added [ExportUsersForMapping](https://nkdagility.com/learn/azure-devops-migration-tools/Reference/v1/Processors/TeamMigrationContext/) to export a json file with a list of users ready for a field mapping. - 13.1 - Update all NuGet packages to latest version. - 13.0 - Update to .net 7.0 with all dependancies. Focus on documentation improvements to support future updates. @@ -107,4 +115,3 @@ We use these tools with our customers, and for fun, to do real world migrations | Security Rating | [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=vsts-sync-migrator%3Amaster&metric=security_rating)](https://sonarcloud.io/dashboard?id=vsts-sync-migrator%3Amaster) | | Vulnerabilities | [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=vsts-sync-migrator%3Amaster&metric=vulnerabilities)](https://sonarcloud.io/dashboard?id=vsts-sync-migrator%3Amaster) | | Release | [![GitHub release](https://img.shields.io/github/release/nkdAgility/vsts-sync-migration.svg)](https://github.com/nkdAgility/azure-devops-migration-tools/releases) | -| Chocolatey |[![Chocolatey](https://img.shields.io/chocolatey/v/vsts-sync-migrator.svg)](https://chocolatey.org/packages/vsts-sync-migrator/)| diff --git a/docs/_data/reference.v1.processors.workitemmigrationcontext.yaml b/docs/_data/reference.v1.processors.workitemmigrationcontext.yaml index ec8ce3f3f..4789832a9 100644 --- a/docs/_data/reference.v1.processors.workitemmigrationcontext.yaml +++ b/docs/_data/reference.v1.processors.workitemmigrationcontext.yaml @@ -38,7 +38,8 @@ configurationSamples: }, "MaxGracefulFailures": 0, "SkipRevisionWithInvalidIterationPath": false, - "SkipRevisionWithInvalidAreaPath": false + "SkipRevisionWithInvalidAreaPath": false, + "ShouldCreateMissingRevisionPaths": true } sampleFor: MigrationTools._EngineV1.Configuration.Processing.WorkItemMigrationConfig description: WorkItemMigrationConfig is the main processor used to Migrate Work Items, Links, and Attachments. Use `WorkItemMigrationConfig` to configure. @@ -118,6 +119,10 @@ options: type: Boolean description: You can choose to migrate the tip only (a single write) or all of the revisions (many writes). If you are setting this to `false` to migrate only the tip then you should set `BuildFieldTable` to `true`. defaultValue: true +- parameterName: ShouldCreateMissingRevisionPaths + type: Boolean + description: When set to True the susyem will try to create any missing missing area or iteration paths from the revisions. + defaultValue: missng XML code comments - parameterName: SkipRevisionWithInvalidAreaPath type: Boolean description: When set to true, this setting will skip a revision if the source area has not been migrated, has been deleted or is somehow invalid, etc. @@ -132,7 +137,7 @@ options: defaultValue: false - parameterName: StopMigrationOnMissingAreaIterationNodes type: Boolean - description: '' + description: With this enabled the system will stop after the check for missing nodes if detected. defaultValue: '?' - parameterName: UpdateCreatedBy type: Boolean diff --git a/docs/collections/_reference/reference.v1.processors.exportusersformapping.md b/docs/collections/_reference/reference.v1.processors.exportusersformapping.md index 6b0484a62..5b0145295 100644 --- a/docs/collections/_reference/reference.v1.processors.exportusersformapping.md +++ b/docs/collections/_reference/reference.v1.processors.exportusersformapping.md @@ -50,8 +50,29 @@ categories: topics: - topic: notes path: /docs/Reference/v1/Processors/ExportUsersForMapping-notes.md - exists: false - markdown: '' + exists: true + markdown: >- + ## Additional Samples & Info + + + ``` + + { + "$type": "ExportUsersForMappingConfig", + "Enabled": false, + "LocalExportJsonFile": "c:\\temp\\ExportUsersForMappingConfig.json", + "WIQLQuery": "SELECT [System.Id], [System.Tags] FROM WorkItems WHERE [System.TeamProject] = @TeamProject AND [System.WorkItemType] NOT IN ('Test Suite', 'Test Plan') ORDER BY [System.ChangedDate] desc", + "IdentityFieldsToCheck": [ + "System.AssignedTo", + "System.ChangedBy", + "System.CreatedBy", + "Microsoft.VSTS.Common.ActivatedBy", + "Microsoft.VSTS.Common.ResolvedBy", + "Microsoft.VSTS.Common.ClosedBy" + ] + } + + ``` - topic: introduction path: /docs/Reference/v1/Processors/ExportUsersForMapping-introduction.md exists: false diff --git a/docs/collections/_reference/reference.v1.processors.workitemmigrationcontext.md b/docs/collections/_reference/reference.v1.processors.workitemmigrationcontext.md index 1e978c442..613e34233 100644 --- a/docs/collections/_reference/reference.v1.processors.workitemmigrationcontext.md +++ b/docs/collections/_reference/reference.v1.processors.workitemmigrationcontext.md @@ -39,7 +39,8 @@ configurationSamples: }, "MaxGracefulFailures": 0, "SkipRevisionWithInvalidIterationPath": false, - "SkipRevisionWithInvalidAreaPath": false + "SkipRevisionWithInvalidAreaPath": false, + "ShouldCreateMissingRevisionPaths": true } sampleFor: MigrationTools._EngineV1.Configuration.Processing.WorkItemMigrationConfig description: WorkItemMigrationConfig is the main processor used to Migrate Work Items, Links, and Attachments. Use `WorkItemMigrationConfig` to configure. @@ -119,6 +120,10 @@ options: type: Boolean description: You can choose to migrate the tip only (a single write) or all of the revisions (many writes). If you are setting this to `false` to migrate only the tip then you should set `BuildFieldTable` to `true`. defaultValue: true +- parameterName: ShouldCreateMissingRevisionPaths + type: Boolean + description: When set to True the susyem will try to create any missing missing area or iteration paths from the revisions. + defaultValue: missng XML code comments - parameterName: SkipRevisionWithInvalidAreaPath type: Boolean description: When set to true, this setting will skip a revision if the source area has not been migrated, has been deleted or is somehow invalid, etc. @@ -133,7 +138,7 @@ options: defaultValue: false - parameterName: StopMigrationOnMissingAreaIterationNodes type: Boolean - description: '' + description: With this enabled the system will stop after the check for missing nodes if detected. defaultValue: '?' - parameterName: UpdateCreatedBy type: Boolean @@ -473,7 +478,26 @@ topics: > Note: This mappings could also be achieved with other forms of Field mapper e.g. `RegexFieldMapConfig`, but the value mapper as an example is easy to understand - topic: introduction path: /docs/Reference/v1/Processors/WorkItemMigrationContext-introduction.md - exists: false - markdown: '' + exists: true + markdown: >+ + The `WorkItemMigrationContext` processor is used for migrating work items from one Azure DevOps instance to another. This encompasses a variety of activities: + + + 1. **Transferring Work Items Between Instances**: The primary purpose of the processor is to transfer work items, including bugs, tasks, user stories, features, and more, from one Azure DevOps instance to another. + + + 2. **Migrating Work Item History**: The processor can also replicate the entire revision history of work items, providing continuity and maintaining a record of changes. + + + 3. **Migrating Attachments and Links**: The processor can transfer any attachments or links associated with work items. This includes both external links and internal links to other work items. + + + 4. **Updating Metadata**: If configured, the processor can update the "Created Date" and "Created By" fields on migrated work items to match the original items in the source instance. + + + 5. **Filtering Work Items**: The processor can be configured to only migrate certain work items based on their area or iteration paths. + + + Overall, the `WorkItemMigrationContext` processor is a comprehensive tool for transferring work items and their associated data and metadata between Azure DevOps instances. It should be used whenever there is a need to move work items between instances while preserving as much information as possible. --- \ No newline at end of file diff --git a/docs/collections/_reference/reference.v2.endpoints.tfsworkitemendpoint.md b/docs/collections/_reference/reference.v2.endpoints.tfsworkitemendpoint.md index 9ade9f86f..f42bcd4f5 100644 --- a/docs/collections/_reference/reference.v2.endpoints.tfsworkitemendpoint.md +++ b/docs/collections/_reference/reference.v2.endpoints.tfsworkitemendpoint.md @@ -28,9 +28,9 @@ topics: The Work Item endpoint is super awesome. - Client | WriteTo/ReadFrom | Endpoint | Data Target | Description + |Client | WriteTo/ReadFrom | Endpoint | Data Target | Description | - ----------|-----------|------------ + |:-:|:-:|:-:|:-:|:-:| AzureDevops.ObjectModel | Tfs Object Model | `TfsWorkItemEndPoint` | WorkItems | TBA diff --git a/docs/faq.md b/docs/faq.md index a4b1b9da8..98f1d7dfc 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -77,8 +77,8 @@ For details on how to add the field in each case, and trouble shooting check the ## Can I disable the telemetry collected and sent to Application Insights? -Yes! You can turn off telemetry from v13.2 by passing `off` as a value for `--telemetry` on the command line. +Yes! You can turn off telemetry from v13.2 by passing `true` as a value for `--disableTelemetry` on the command line. ``` -migration.exe --config configuration.json --telemetry off +devops-migration.exe --config configuration.json --disableTelemetry true ``` diff --git a/docs/getting-started.md b/docs/getting-started.md index ee2f2dce5..f7d4a82a4 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -17,14 +17,14 @@ Watch the [Video Overview](https://youtu.be/RCJsST0xBCE) to get started in 30 mi In order to run the migration you will need to install the tools first. -1. Install Chocolatey from [https://chocolatey.org/install](https://chocolatey.org/install) -1. Run `choco install vsts-sync-migrator` to install the tools [source](https://chocolatey.org/packages/vsts-sync-migrator) +1. Install [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/) +1. Run `winget install nkdAgility.AzureDevOpsMigrationTools` from the [Windows Terminal](https://learn.microsoft.com/en-us/windows/terminal/) to install on Windows 10 and Windows 11. For other operating systems you can download the [latest release](https://github.com/nkdAgility/azure-devops-migration-tools/releases/latest) and unzip it to a folder of your choice. -The tools are now installed. To run them, you must switch to `c:\tools\MigrationTools\` and run `migration.exe`. +The tools will be installed to `%Localappdata%\Microsoft\WinGet\Packages\nkdAgility.AzureDevOpsMigrationTools_Microsoft.Winget.Source_XXXXXXXXXX` and a symbolic link to `devops-migration.exe` that lets you run it from anywhere using `devops-migration init`. ## Upgrade -1. Run `choco upgrade vsts-sync-migrator` to upgrade the tools [source](https://chocolatey.org/packages/vsts-sync-migrator) +1. Run `winget upgrade nkdAgility.AzureDevOpsMigrationTools` to upgrade the tools. ## Server configuration and setup @@ -32,8 +32,8 @@ Follow the [setup instructions](server-configuration.md) to make sure that you c ## Create a default configuration file -1. Open a command prompt or PowerShell window at `C:\tools\MigrationTools\` -2. Run `./migration.exe init` to create a default configuration +1. Open your [Windows Terminal](https://learn.microsoft.com/en-us/windows/terminal/) in your chosen working folder +2. Run `migration init` to create a default configuration 3. Open `configuration.json` from the current directory You can now customize the configuration depending on what you need to do. However, a basic config that you can use to migrate from one team project to another with the same process template is: @@ -70,14 +70,14 @@ The default [WorkItemMigrationConfig](/docs/Reference/v1/Processors/WorkItemMigr 5. Enable the `WorkItemMigrationConfig` processor by setting `Enabled` to `true` 6. [OPTIONAL] Modify the `WIQLQueryBit` to migrate only the work items you want. The default WIQL will migrate all open work items and revisions excluding test suites and plans 7. Adjust the [`NodeBasePaths`](/docs/Reference/v1/Processors/WorkItemMigrationConfig.md) or leave empty to migrate all nodes -8. From the `C:\tools\MigrationTools\` path run `.\migration.exe execute --config .\configuration.json` +8. From your working folder run `devops-migration execute --config .\configuration.json` **Remember:** If you want a processor to run, its `Enabled` attribute must be set to `true`. Refer to the [Reference Guide](/docs/Reference/index.md) for more details. ## Other Configuration Options -When running `./migration.exe init` you can also pass `--options` with one of the following: +When running `devops-migration init` you can also pass `--options` with one of the following: - *Full* - - *WorkItemTracking* - diff --git a/docs/index.md b/docs/index.md index ec505a0e9..a943126e0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,7 +8,7 @@ pageStatus: published discussionId: --- -[![Chocolatey](https://img.shields.io/chocolatey/dt/vsts-sync-migrator.svg)](https://chocolatey.org/packages/vsts-sync-migrator/) [![GitHub release](https://img.shields.io/github/release/nkdAgility/vsts-sync-migration.svg)](https://github.com/nkdAgility/azure-devops-migration-tools/releases) ![Build on VSTS](https://nkdagility.visualstudio.com/_apis/public/build/definitions/1b52ce63-eccc-41c8-88f9-ae6ebeefdc63/94/badge) +[![GitHub release](https://img.shields.io/github/release/nkdAgility/vsts-sync-migration.svg)](https://github.com/nkdAgility/azure-devops-migration-tools/releases) ![Build on VSTS](https://nkdagility.visualstudio.com/_apis/public/build/definitions/1b52ce63-eccc-41c8-88f9-ae6ebeefdc63/94/badge) The Azure DevOps Migration Tools allow you to bulk edit and migrate data between Team Projects on both Microsoft Team Foundation Server (TFS) and Azure DevOps Services. Take a look at the [documentation](https://nkdagility.com/docs/azure-devops-migration-tools/) to find out how. This project is published as [code on GitHub](https://github.com/nkdAgility/azure-devops-migration-tools/) as well as a [Azure DevOps Migration Tools on Chocolatey](https://chocolatey.org/packages/vsts-sync-migrator/). diff --git a/src/MigrationTools.Clients.AzureDevops.ObjectModel.Tests/MigrationTools.Clients.AzureDevops.ObjectModel.Tests.csproj b/src/MigrationTools.Clients.AzureDevops.ObjectModel.Tests/MigrationTools.Clients.AzureDevops.ObjectModel.Tests.csproj index 73f8d6f79..248001548 100644 --- a/src/MigrationTools.Clients.AzureDevops.ObjectModel.Tests/MigrationTools.Clients.AzureDevops.ObjectModel.Tests.csproj +++ b/src/MigrationTools.Clients.AzureDevops.ObjectModel.Tests/MigrationTools.Clients.AzureDevops.ObjectModel.Tests.csproj @@ -11,7 +11,7 @@ - + diff --git a/src/MigrationTools.Clients.AzureDevops.Rest.Tests/MigrationTools.Clients.AzureDevops.Rest.Tests.csproj b/src/MigrationTools.Clients.AzureDevops.Rest.Tests/MigrationTools.Clients.AzureDevops.Rest.Tests.csproj index 2bc29a20e..45b4872f0 100644 --- a/src/MigrationTools.Clients.AzureDevops.Rest.Tests/MigrationTools.Clients.AzureDevops.Rest.Tests.csproj +++ b/src/MigrationTools.Clients.AzureDevops.Rest.Tests/MigrationTools.Clients.AzureDevops.Rest.Tests.csproj @@ -8,7 +8,7 @@ - + diff --git a/src/MigrationTools.Clients.FileSystem.Tests/MigrationTools.Clients.FileSystem.Tests.csproj b/src/MigrationTools.Clients.FileSystem.Tests/MigrationTools.Clients.FileSystem.Tests.csproj index 4dece9b1c..585f6e4ed 100644 --- a/src/MigrationTools.Clients.FileSystem.Tests/MigrationTools.Clients.FileSystem.Tests.csproj +++ b/src/MigrationTools.Clients.FileSystem.Tests/MigrationTools.Clients.FileSystem.Tests.csproj @@ -11,7 +11,7 @@ - + diff --git a/src/MigrationTools.Clients.InMemory.Tests/MigrationTools.Clients.InMemory.Tests.csproj b/src/MigrationTools.Clients.InMemory.Tests/MigrationTools.Clients.InMemory.Tests.csproj index 1896cc5e6..657d04189 100644 --- a/src/MigrationTools.Clients.InMemory.Tests/MigrationTools.Clients.InMemory.Tests.csproj +++ b/src/MigrationTools.Clients.InMemory.Tests/MigrationTools.Clients.InMemory.Tests.csproj @@ -11,7 +11,7 @@ - + diff --git a/src/MigrationTools.ConsoleDataGenerator/MigrationTools.ConsoleDataGenerator.csproj b/src/MigrationTools.ConsoleDataGenerator/MigrationTools.ConsoleDataGenerator.csproj index 0b3337b3f..274d727da 100644 --- a/src/MigrationTools.ConsoleDataGenerator/MigrationTools.ConsoleDataGenerator.csproj +++ b/src/MigrationTools.ConsoleDataGenerator/MigrationTools.ConsoleDataGenerator.csproj @@ -16,7 +16,7 @@ - + diff --git a/src/MigrationTools.ConsoleFull/MigrationTools.ConsoleFull.csproj b/src/MigrationTools.ConsoleFull/MigrationTools.ConsoleFull.csproj index 3d9d2794c..18825330e 100644 --- a/src/MigrationTools.ConsoleFull/MigrationTools.ConsoleFull.csproj +++ b/src/MigrationTools.ConsoleFull/MigrationTools.ConsoleFull.csproj @@ -4,7 +4,7 @@ Exe net472 Azure DevOps Migration Tools [Object Model] - migration + devops-migration AnyCPU diff --git a/src/MigrationTools.Extension/README.md b/src/MigrationTools.Extension/README.md index 2a0097ed5..5ba1d0b69 100644 --- a/src/MigrationTools.Extension/README.md +++ b/src/MigrationTools.Extension/README.md @@ -1,7 +1,6 @@ -# Azure DevOps Migration Tools [![Chocolatey](https://img.shields.io/chocolatey/dt/vsts-sync-migrator.svg)](https://chocolatey.org/packages/vsts-sync-migrator/) [![GitHub release](https://img.shields.io/github/release/nkdAgility/vsts-sync-migration.svg)](https://github.com/nkdAgility/azure-devops-migration-tools/releases) ![Build on VSTS](https://nkdagility.visualstudio.com/_apis/public/build/definitions/1b52ce63-eccc-41c8-88f9-ae6ebeefdc63/94/badge) - -The Azure DevOps Migration Tools allow you to bulk edit and migrate data between Team Projects on both Microsoft Team Foundation Server (TFS) and Azure DevOps Services. Take a look at the [documentation](https://nkdagility.com/docs/azure-devops-migration-tools/) to find out how. This project is published as [code on GitHub](https://github.com/nkdAgility/azure-devops-migration-tools/) as well as a [Azure DevOps Migration Tools on Chocolatey](https://chocolatey.org/packages/vsts-sync-migrator/). +# Azure DevOps Migration Tools [![GitHub release](https://img.shields.io/github/release/nkdAgility/vsts-sync-migration.svg)](https://github.com/nkdAgility/azure-devops-migration-tools/releases) ![Build on VSTS](https://nkdagility.visualstudio.com/_apis/public/build/definitions/1b52ce63-eccc-41c8-88f9-ae6ebeefdc63/94/badge) +The Azure DevOps Migration Tools allow you to bulk edit and migrate data between Team Projects on both Microsoft Team Foundation Server (TFS) and Azure DevOps Services. Take a look at the [documentation](https://nkdagility.com/docs/azure-devops-migration-tools/) to find out how. This project is published as [code on GitHub](https://github.com/nkdAgility/azure-devops-migration-tools/) as well as a Winget package a `nkdAgility.AzureDevOpsMigrationTools`. **Ask Questions on Github: https://github.com/nkdAgility/azure-devops-migration-tools/discussions** @@ -53,6 +52,14 @@ The Azure DevOps Migration Tools allow you to bulk edit and migrate data between - [Questions on Usage](https://stackoverflow.com/questions/tagged/azure-devops-migration-tools) - [Bugs and New Features](https://github.com/nkdAgility/azure-devops-migration-tools) + ## Installing an running the tools + +We use [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/) to host the tools, and you can use the command `winget install nkdAgility.AzureDevOpsMigrationTools` to install them on Windows 10 and Windows 11. For other operating systems you can download the [latest release](https://github.com/nkdAgility/azure-devops-migration-tools/releases/latest) and unzip it to a folder of your choice. + +The tools will be installed to `%Localappdata%\Microsoft\WinGet\Packages\nkdAgility.AzureDevOpsMigrationTools_Microsoft.Winget.Source_XXXXXXXXXX` and a symbolic link to `devops-migration.exe` that lets you run it from anywhere using `devops-migration init`. + +For a more detailed getting started guide please see the [documentation](https://nkdagility.com/docs/azure-devops-migration-tools/getting-started.html). + ## Support 1. [Question & Discussion](https://github.com/nkdAgility/azure-devops-migration-tools/discussions) - The first place to look for unsage, configuration, and general help. @@ -66,39 +73,4 @@ We use these tools with our customers, and for fun, to do real world migrations - Consult with your internal folks who need help and guidance in runnign the tooling. - Make changes to the tool to support your needs; all additions are commited to the main repo. - - Run the migration for you:- you would need to pay for the hours that we would spend baby-sitting the running migrations - - -## Change Log - -- v11.11 - Refactored revision manager to have more tests and support limiting the number of revisions. CollapseRevisions has been replaced by setting MaxRevisions to 1 and setting AttachRevisionHistory to true; MaxRevisions sets the maximum number of revisions that will be migrated. "First + Last*N = Max". If this was set to 5 and there were 10 revisions you would get the first 1 (creation) and the latest 4 migrated. This is done after all of the existing revisions are created but before anything newer that target is removed. -- v11.10 - Added ability to limit the number of revisions migrated with `MaxRevisions` on `WorkItemMigration` processor. 0 = All, and any other number should migrate the first revision + the latest up to MAX. -- v11.9 - Dark launch of `Process` migration by @akanieski -- v11.9 - Dark launch of `Pipelines` & `Builds` migration by @tomfrenzel -- v11.8 - As part of moving to the new architecture we moved to default newtonsoft type handling with `$type` properties instead of `ObjectType` ___To Migrate rename "ObjectType" to "$type" in your configuration!___ -- v11.5 - Added more useful logging levels. Replace `"TelemetryEnableTrace": false` with `"LogLevel": "Verbose"` in the config. Verbose will only be logged to the logfile. -- v11.2.1 - Removed NodeMigrationContext and converted it to an enricher for Work Items. Still needs work, so that it migrates individual nodes, but currently migrates all. -- v10.1 - Changed config design to have only the Name and not FullName of the class. Remove `MigrationTools.Core.Configuration.FieldMap.` and `MigrationTools.Core.Configuration.Processing.` from the config leaving only the Name of the class in ObjectType field. -- v10.0 - Start of the great refactor over to .NET Core and the REST API as the Object Model has been retired. -- v9.0 - Added support for migration between other language versions of Azure DevOps. Developed for German -> English -- v8.9 - Added 'Collapse Revisions' feature to collapse and attache revisions instead of replaying them -- v8.8 - 'SkipToFinalRevisedWorkItemType' feature added to handle scenario when changing Work Item Type -- v8.7 - Support for inline images using a Personal Access Token added to the Source Project -- v8.6 - Support for fixing links from TFVC Changesets to Git Commits using a mapping file generated from a Git-TFS migration. -- v8.5 - Attachment Max size and linking work items to git repos between projects. -- v8.4 - Support for cross-project linking of work items between projects. -- v8.3 - Support for restarting the migration and syncing at the revision level. -- v8.2 - Merge Git commit Fixing into Work Item migration (requires repos to be migrated first, can be rerun) -- v8.0 - Merge of Work Item, Link, & attachment migrators into one. - -## The Technical Details - -|-| Technical Overview | -|-------------:|:-------------| -| Azure Pipeline | ![Build on VSTS](https://nkdagility.visualstudio.com/_apis/public/build/definitions/1b52ce63-eccc-41c8-88f9-ae6ebeefdc63/94/badge) | -| Coverage | [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=vsts-sync-migrator%3Amaster&metric=coverage)](https://sonarcloud.io/dashboard?id=vsts-sync-migrator%3Amaster) | -| Maintainability | [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=vsts-sync-migrator%3Amaster&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=vsts-sync-migrator%3Amaster) | -| Security Rating | [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=vsts-sync-migrator%3Amaster&metric=security_rating)](https://sonarcloud.io/dashboard?id=vsts-sync-migrator%3Amaster) | -| Vulnerabilities | [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=vsts-sync-migrator%3Amaster&metric=vulnerabilities)](https://sonarcloud.io/dashboard?id=vsts-sync-migrator%3Amaster) | -| Release | [![GitHub release](https://img.shields.io/github/release/nkdAgility/vsts-sync-migration.svg)](https://github.com/nkdAgility/azure-devops-migration-tools/releases) | -| Chocolatey |[![Chocolatey](https://img.shields.io/chocolatey/v/vsts-sync-migrator.svg)](https://chocolatey.org/packages/vsts-sync-migrator/)| + - Run the migration for you:- you would need to pay for the hours that we would spend baby-sitting the running migrations \ No newline at end of file diff --git a/src/MigrationTools.Host.Tests/MigrationTools.Host.Tests.csproj b/src/MigrationTools.Host.Tests/MigrationTools.Host.Tests.csproj index 8ca611512..51b0d48dc 100644 --- a/src/MigrationTools.Host.Tests/MigrationTools.Host.Tests.csproj +++ b/src/MigrationTools.Host.Tests/MigrationTools.Host.Tests.csproj @@ -16,7 +16,7 @@ - + diff --git a/src/MigrationTools.Host/MigrationTools.Host.csproj b/src/MigrationTools.Host/MigrationTools.Host.csproj index fed802c75..f4d5ccb27 100644 --- a/src/MigrationTools.Host/MigrationTools.Host.csproj +++ b/src/MigrationTools.Host/MigrationTools.Host.csproj @@ -15,12 +15,12 @@ - + - + - + diff --git a/src/MigrationTools.Host/Services/DetectVersionService.cs b/src/MigrationTools.Host/Services/DetectVersionService.cs index 30f2c373e..b4289a5a7 100644 --- a/src/MigrationTools.Host/Services/DetectVersionService.cs +++ b/src/MigrationTools.Host/Services/DetectVersionService.cs @@ -33,7 +33,7 @@ public Version GetLatestVersion() try { //Connect to the official package repository - IEnumerable versions = GetVersions(packageID); + IEnumerable versions = GetChocoVersions(packageID); latestPackageVersion = versions.Max(p => p.Version); if (latestPackageVersion != null) { @@ -52,7 +52,7 @@ public Version GetLatestVersion() return latestPackageVersion; } - private IEnumerable GetVersions(string packageId, string sourceUrl = "https://chocolatey.org/api/v2/") + private IEnumerable GetChocoVersions(string packageId, string sourceUrl = "https://chocolatey.org/api/v2/") { NuGet.Common.ILogger logger = NullLogger.Instance; CancellationToken cancellationToken = CancellationToken.None; diff --git a/src/MigrationTools.Host/StartupService.cs b/src/MigrationTools.Host/StartupService.cs index 723f2ff66..ee1d4449c 100644 --- a/src/MigrationTools.Host/StartupService.cs +++ b/src/MigrationTools.Host/StartupService.cs @@ -46,7 +46,7 @@ public void RunStartupLogic(string[] args) var version = Assembly.GetEntryAssembly().GetName().Version; if (latestVersion > version && args.Contains("skipVersionCheck")) { - _logger.LogWarning("You are currently running version {Version} and a newer version ({LatestVersion}) is available. You should upgrade now using Chocolatey command 'choco upgrade vsts-sync-migrator' from the command line.", version, latestVersion); + _logger.LogWarning("You are currently running version {Version} and a newer version ({LatestVersion}) is available. You should update now using Winget command 'winget nkdAgility.AzureDevOpsMigrationTools' from the Windows Terminal.", version, latestVersion); #if !DEBUG Console.WriteLine("Do you want to continue? (y/n)"); if (Console.ReadKey().Key != ConsoleKey.Y) @@ -91,7 +91,7 @@ private void ApplicationStartup(string[] args) var version = Assembly.GetEntryAssembly().GetName().Version; _logger.LogInformation("Application Starting"); AsciiLogo(version); - _logger.LogInformation("Telemetry Note: We use Application Insights to collect telemetry on performance & feature usage for the tools to help our developers target features. This data is tied to a session ID that is generated and shown in the logs. This can help with debugging. If you want to disable telemitery you can run the tool with '--disableTelemitery true' on the command prompt."); + TelemetryNote(); _logger.LogInformation("Start Time: {StartTime}", DateTime.Now.ToUniversalTime().ToLocalTime()); _logger.LogInformation("Running with args: {@Args}", args); _logger.LogInformation("OSVersion: {OSVersion}", Environment.OSVersion.ToString()); @@ -105,6 +105,19 @@ protected void CurrentDomain_UnhandledException(object sender, UnhandledExceptio System.Threading.Thread.Sleep(5000); } + private void TelemetryNote() + { + _logger.LogInformation("Telemetry Note:"); + _logger.LogInformation(" We use Application Insights to collect usage and error information in order to improve the quality of the tools."); + _logger.LogInformation(" Currently we collect the following anonymous data:"); + _logger.LogInformation(" -Event data: application version, client city/country, hosting type, item count, error count, warning count, elapsed time."); + _logger.LogInformation(" -Exceptions: application errors and warnings."); + _logger.LogInformation(" -Dependencies: REST/ObjectModel calls to Azure DevOps to help us understand performance issues."); + _logger.LogInformation(" This data is tied to a session ID that is generated on each run of the application and shown in the logs. This can help with debugging. If you want to disable telemetry you can run the tool with '--disableTelemetry true' on the command prompt."); + _logger.LogInformation(" Note: Exception data cannot be 100% guaranteed to not leak production data"); + _logger.LogInformation("--------------------------------------"); + } + private void AsciiLogo(Version thisVersion) { _logger.LogInformation(" &@& "); diff --git a/src/MigrationTools.Integration.Tests/MigrationTools.Integration.Tests.csproj b/src/MigrationTools.Integration.Tests/MigrationTools.Integration.Tests.csproj index 727c189c7..2c3b22a37 100644 --- a/src/MigrationTools.Integration.Tests/MigrationTools.Integration.Tests.csproj +++ b/src/MigrationTools.Integration.Tests/MigrationTools.Integration.Tests.csproj @@ -9,7 +9,7 @@ - + diff --git a/src/MigrationTools.Tests/MigrationTools.Tests.csproj b/src/MigrationTools.Tests/MigrationTools.Tests.csproj index 13f029d20..e24d3d067 100644 --- a/src/MigrationTools.Tests/MigrationTools.Tests.csproj +++ b/src/MigrationTools.Tests/MigrationTools.Tests.csproj @@ -10,7 +10,7 @@ - + diff --git a/src/MigrationTools/_EngineV1/Configuration/EngineConfigurationBuilder.cs b/src/MigrationTools/_EngineV1/Configuration/EngineConfigurationBuilder.cs index 8b07bc9f0..4c6ec4b7f 100644 --- a/src/MigrationTools/_EngineV1/Configuration/EngineConfigurationBuilder.cs +++ b/src/MigrationTools/_EngineV1/Configuration/EngineConfigurationBuilder.cs @@ -48,7 +48,7 @@ public EngineConfiguration BuildFromFile(string configFile = "configuration.json _logger.LogTrace(ex, "Configuration Error"); _logger.LogCritical("Your configuration file was loaded but was unable to be mapped to "); _logger.LogError(ex.Message); - _logger.LogError("How to Solve: Malformed configurations are usually a result of changes between versions. The best way to understand the change is to run 'migration.exe init' to create a new wel formed config and determin where the problem is!"); + _logger.LogError("How to Solve: Malformed configurations are usually a result of changes between versions. The best way to understand the change is to run 'devops-migration init' to create a new wel formed config and determin where the problem is!"); Environment.Exit(-1); return null; } diff --git a/src/VstsSyncMigrator.Core.Tests/VstsSyncMigrator.Core.Tests.csproj b/src/VstsSyncMigrator.Core.Tests/VstsSyncMigrator.Core.Tests.csproj index 8e6fb5143..1c479a5fd 100644 --- a/src/VstsSyncMigrator.Core.Tests/VstsSyncMigrator.Core.Tests.csproj +++ b/src/VstsSyncMigrator.Core.Tests/VstsSyncMigrator.Core.Tests.csproj @@ -7,8 +7,8 @@ - - + +