[preview] Documentation cleanup and Test fix for PrefixProjectName (#…

…1967)
nkdAgility · Mar 5, 2024 · 6fe4619 · 6fe4619
1 parent dacb634
commit 6fe4619
Show file tree

Hide file tree

Showing 16 changed files with 146 additions and 103 deletions.
diff --git a/docs/Reference/v1/Processors/WorkItemMigrationContext-notes.md b/docs/Reference/v1/Processors/WorkItemMigrationContext-notes.md
@@ -41,11 +41,11 @@ Scope to Area Path (Team data):
 
 ## <a name="NodeBasePath"></a>NodeBasePath Configuration 
 
-Moved to the ProcessorEnricher [TfsNodeStructure](../Reference/v2/ProcessorEnrichers/TfsNodeStructure/)
+Moved to the ProcessorEnricher [TfsNodeStructure](/Reference/v2/ProcessorEnrichers/TfsNodeStructure/)
 
 # Iteration Maps and Area Maps
 
-Moved to the ProcessorEnricher [TfsNodeStructure](../Reference/v2/ProcessorEnrichers/TfsNodeStructure/)
+Moved to the ProcessorEnricher [TfsNodeStructure](/Reference/v2/ProcessorEnrichers/TfsNodeStructure/)
 
 
 
@@ -78,4 +78,4 @@ A complete list of [FieldMaps](../Reference/v1/FieldMaps/index.md) are available
 
 # Removed Properties
 
-- PrefixProjectToNodes - This option was removed in favour of the Area and Iteration Maps on [TfsNodeStructure](../Reference/v2/ProcessorEnrichers/TfsNodeStructure/)
+- PrefixProjectToNodes - This option was removed in favour of the Area and Iteration Maps on [TfsNodeStructure](/Reference/v2/ProcessorEnrichers/TfsNodeStructure/)
diff --git a/docs/Reference/v2/ProcessorEnrichers/TfsNodeStructure-notes.md b/docs/Reference/v2/ProcessorEnrichers/TfsNodeStructure-notes.md
@@ -109,6 +109,20 @@ in the replacement string.
  `TargetProject\NewArea\ValidArea\` but `OriginalProject\DescopeThis` would not
  be modified by this rule.
 
+### PrefixProjectToNodes
+
+The `PrefixProjectToNodes` was an option that was used to prepend the source project name to the target set of nodes. This was super valuable when the target Project already has nodes and you dont want to merge them all together. This is now replaced by the `AreaMaps` and `IterationMaps` options.
+
+```
+"IterationMaps": {
+ "^SourceServer\\\\(.*)" , "TargetServer\\SourceServer\\$1",
+},
+"AreaMaps": {
+ "^SourceServer\\\\(.*)" , "TargetServer\\SourceServer\\$1",
+}
+```
+
+
 ### More Complex Regex
 
 Before your migration starts it will validate that all of the Areas and Iterations from the **Source** work items revisions exist on the **Target**. Any that do not exist will be flagged in the logs and if and the migration will stop just after it outputs a list of the missing nodes.

diff --git a/docs/collections/_reference/reference.v2.processorenrichers.tfsnodestructure.md b/docs/collections/_reference/reference.v2.processorenrichers.tfsnodestructure.md
@@ -69,73 +69,25 @@ topics:
 - topic: notes
  path: /docs/Reference/v2/ProcessorEnrichers/TfsNodeStructure-notes.md
  exists: true
- markdown: >-
- ## <a name="NodeBasePath"></a>NodeBasePath Configuration ##
+ markdown: >2-
 
- The `NodeBasePaths` entry allows the filtering of the nodes to be replicated on the target projects. To try to explain the correct usage let us assume that we have a source team project `SourceProj` with the following node structures
-
-
- - AreaPath
- - SourceProj
- - SourceProj\Team 1
- - SourceProj\Team 2
- - SourceProj\Team 2\Sub-Area
- - SourceProj\Team 3
- - IterationPath
- - SourceProj
- - SourceProj\Sprint 1
- - SourceProj\Sprint 2
- - SourceProj\Sprint 2\Sub-Iteration
- - SourceProj\Sprint 3
-
- Depending upon what node structures you wish to migrate you would need the following settings. Exclusions are also possible by prefixing a path with an exclamation mark `!`. Example are
-
-
- | | |
-
- |-|-|
-
- | Intention | Migrate all areas and iterations and all Work Items
-
- | NodeBasePath | `[]`
-
- | Comment | The same AreaPath and Iteration Paths are created on the target as on the source. Hence, all migrated WI remain in their existing area and iteration paths
-
- ||
 
- | Intention | Only migrate area path `Team 2` and it associated Work Items, but all iteration paths
 
- | NodeBasePath | `["Team 2", "Sprint"]`
+ ## Iteration Maps and Area Maps
 
- | Comment | Only the area path ending `Team 2` will be migrated. <br>The `WIQLQueryBit` should be edited to limit the WI migrated to this area path e.g. add `AND [System.AreaPath] UNDER 'SampleProject\\Team 2'` . <br> The migrated WI will have an area path of `TargetProj\Team 2` but retain their iteration paths matching the sprint name on the source
 
- ||
+ **NOTE: It is NOT posible to migrate a work item if the Area or Iteration path does not exist on the target project. This is because the work item will be created with the same Area and Iteration path as the source work item. If the path does not exist, the work item will not be created. _There is not way around this!_**
 
- | Intention | Only migrate iterations structure
 
- | NodeBasePath | `["Sprint"]`
+ You have two options to solve this problem:
 
- | Comment | Only the area path ending `Team 2` will be migrated<br>All the iteration paths will be migrated. <br> The migrated WI will have the default area path of `TargetProj` as their source area path was not migrated i.e. `TargetProj`<br> The migrated WI will have an iteration path match the sprint name on the source
 
- ||
+ 1. You can manualy create the mentioned work items. This is a good option if you have a small number of work items or a small number of missing nodes. This will not work if you have work items that were moved from one project to another. Those Nodes are imposible to create in the target project.
 
- | Intention | Move all WI to the existing area and iteration paths on the targetProj
+ 1. You can use the `AreaMaps` and `IterationMaps` to remap the nodes to existing nodes in the target project. This is a good option if you have a large number of work items or a large number of missing nodes.
 
- | NodeBasePath | `["DUMMY VALUE"]`
 
- | Comment | As the `NodeBasePath` does not match any source area or iteration path no nodes are migrated. <br>Migrated WI will be assigned to any matching area or iteration paths. If no matching ones can be found they will default to the respective root values
-
- ||
-
- | Intention | Move the `Team 2` area, but not its `Sub-Area`
-
- | NodeBasePath | `["Team 2", "!Team 2\\SubArea"]`
-
- | Comment | The Work Items will have to be restricted to the right areas, e.g. with `AND [System.AreaPath] UNDER 'SampleProject\\Team 2' AND [System.AreaPath] NOT UNDER 'SampleProject\\Team 2\\Sub-Area'`, otherwise their migratin will fail
-
-
-
- # Iteration Maps and Area Maps
+ ### Overview
 
 
  These two configuration elements apply after the `NodeBasePaths` selector, i.e.
@@ -201,7 +153,8 @@ topics:
  in the replacement string.
 
 
- #### Examples explained
+
+ ### Configuration
 
 
  ```json
@@ -273,13 +226,13 @@ topics:
  Before your migration starts it will validate that all of the Areas and Iterations from the **Source** work items revisions exist on the **Target**. Any that do not exist will be flagged in the logs and if and the migration will stop just after it outputs a list of the missing nodes.
 
 
- Our algorithm that converts the Source nodes to Target nodes processes the [mappings](https://nkdagility.com/learn/azure-devops-migration-tools/Reference/v1/Processors/WorkItemMigrationContext/#iteration-maps-and-area-maps) at that time. This means that any valid mapped nodes will never be caught by the `This path is not anchored in the source project` message as they are already altered to be valid.
+ Our algorithm that converts the Source nodes to Target nodes processes the mappings at that time. This means that any valid mapped nodes will never be caught by the `This path is not anchored in the source project` message as they are already altered to be valid.
 
 
  > We recently updated the logging for this part of the system to more easily debug both your mappings and to see what they system is doing with the nodes and their current state. You can set `"LogLevel": "Debug"` to see the details.
 
 
- To add a mapping, you can follow [the documentation](https://nkdagility.com/learn/azure-devops-migration-tools/Reference/v1/Processors/WorkItemMigrationContext/#iteration-maps-and-area-maps) with this being the simplest way:
+ To add a mapping, you can follow the documentation with this being the simplest way:
 
 
  ```
@@ -381,6 +334,70 @@ topics:
  ],
 
  ```
+
+
+ ## <a name="NodeBasePath"></a>NodeBasePath Configuration
+
+ The `NodeBasePaths` entry allows the filtering of the nodes to be replicated on the target projects. To try to explain the correct usage let us assume that we have a source team project `SourceProj` with the following node structures
+
+
+ - AreaPath
+ - SourceProj
+ - SourceProj\Team 1
+ - SourceProj\Team 2
+ - SourceProj\Team 2\Sub-Area
+ - SourceProj\Team 3
+ - IterationPath
+ - SourceProj
+ - SourceProj\Sprint 1
+ - SourceProj\Sprint 2
+ - SourceProj\Sprint 2\Sub-Iteration
+ - SourceProj\Sprint 3
+
+ Depending upon what node structures you wish to migrate you would need the following settings. Exclusions are also possible by prefixing a path with an exclamation mark `!`. Example are
+
+
+ | | |
+
+ |-|-|
+
+ | Intention | Migrate all areas and iterations and all Work Items
+
+ | NodeBasePath | `[]`
+
+ | Comment | The same AreaPath and Iteration Paths are created on the target as on the source. Hence, all migrated WI remain in their existing area and iteration paths
+
+ ||
+
+ | Intention | Only migrate area path `Team 2` and it associated Work Items, but all iteration paths
+
+ | NodeBasePath | `["Team 2", "Sprint"]`
+
+ | Comment | Only the area path ending `Team 2` will be migrated. <br>The `WIQLQueryBit` should be edited to limit the WI migrated to this area path e.g. add `AND [System.AreaPath] UNDER 'SampleProject\\Team 2'` . <br> The migrated WI will have an area path of `TargetProj\Team 2` but retain their iteration paths matching the sprint name on the source
+
+ ||
+
+ | Intention | Only migrate iterations structure
+
+ | NodeBasePath | `["Sprint"]`
+
+ | Comment | Only the area path ending `Team 2` will be migrated<br>All the iteration paths will be migrated. <br> The migrated WI will have the default area path of `TargetProj` as their source area path was not migrated i.e. `TargetProj`<br> The migrated WI will have an iteration path match the sprint name on the source
+
+ ||
+
+ | Intention | Move all WI to the existing area and iteration paths on the targetProj
+
+ | NodeBasePath | `["DUMMY VALUE"]`
+
+ | Comment | As the `NodeBasePath` does not match any source area or iteration path no nodes are migrated. <br>Migrated WI will be assigned to any matching area or iteration paths. If no matching ones can be found they will default to the respective root values
+
+ ||
+
+ | Intention | Move the `Team 2` area, but not its `Sub-Area`
+
+ | NodeBasePath | `["Team 2", "!Team 2\\SubArea"]`
+
+ | Comment | The Work Items will have to be restricted to the right areas, e.g. with `AND [System.AreaPath] UNDER 'SampleProject\\Team 2' AND [System.AreaPath] NOT UNDER 'SampleProject\\Team 2\\Sub-Area'`, otherwise their migratin will fail
 - topic: introduction
  path: /docs/Reference/v2/ProcessorEnrichers/TfsNodeStructure-introduction.md
  exists: true

diff --git a/...AzureDevops.ObjectModel.Tests/MigrationTools.Clients.AzureDevops.ObjectModel.Tests.csproj b/...AzureDevops.ObjectModel.Tests/MigrationTools.Clients.AzureDevops.ObjectModel.Tests.csproj
@@ -11,11 +11,11 @@
  <ItemGroup>
  <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
  <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="8.0.0" />
- <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
+ <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.9.0" />
  <PackageReference Include="Microsoft.TeamFoundationServer.ExtendedClient" Version="16.205.1" />
- <PackageReference Include="MSTest.TestAdapter" Version="3.2.0" />
- <PackageReference Include="MSTest.TestFramework" Version="3.2.0" />
- <PackageReference Include="coverlet.collector" Version="6.0.0">
+ <PackageReference Include="MSTest.TestAdapter" Version="3.2.2" />
+ <PackageReference Include="MSTest.TestFramework" Version="3.2.2" />
+ <PackageReference Include="coverlet.collector" Version="6.0.1">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
  </PackageReference>

diff --git a/...Tools.Clients.AzureDevops.Rest.Tests/MigrationTools.Clients.AzureDevops.Rest.Tests.csproj b/...Tools.Clients.AzureDevops.Rest.Tests/MigrationTools.Clients.AzureDevops.Rest.Tests.csproj
@@ -8,10 +8,10 @@
 
  <ItemGroup>
  <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="8.0.0" />
- <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
- <PackageReference Include="MSTest.TestAdapter" Version="3.2.0" />
- <PackageReference Include="MSTest.TestFramework" Version="3.2.0" />
- <PackageReference Include="coverlet.collector" Version="6.0.0">
+ <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.9.0" />
+ <PackageReference Include="MSTest.TestAdapter" Version="3.2.2" />
+ <PackageReference Include="MSTest.TestFramework" Version="3.2.2" />
+ <PackageReference Include="coverlet.collector" Version="6.0.1">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
  </PackageReference>

diff --git a/src/MigrationTools.Clients.FileSystem.Tests/MigrationTools.Clients.FileSystem.Tests.csproj b/src/MigrationTools.Clients.FileSystem.Tests/MigrationTools.Clients.FileSystem.Tests.csproj
@@ -11,10 +11,10 @@
  <ItemGroup>
  <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
  <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="8.0.0" />
- <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
- <PackageReference Include="MSTest.TestAdapter" Version="3.2.0" />
- <PackageReference Include="MSTest.TestFramework" Version="3.2.0" />
- <PackageReference Include="coverlet.collector" Version="6.0.0">
+ <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.9.0" />
+ <PackageReference Include="MSTest.TestAdapter" Version="3.2.2" />
+ <PackageReference Include="MSTest.TestFramework" Version="3.2.2" />
+ <PackageReference Include="coverlet.collector" Version="6.0.1">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
  </PackageReference>

diff --git a/src/MigrationTools.Clients.InMemory.Tests/MigrationTools.Clients.InMemory.Tests.csproj b/src/MigrationTools.Clients.InMemory.Tests/MigrationTools.Clients.InMemory.Tests.csproj
@@ -11,10 +11,10 @@
  <ItemGroup>
  <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
  <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="8.0.0" />
- <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
- <PackageReference Include="MSTest.TestAdapter" Version="3.2.0" />
- <PackageReference Include="MSTest.TestFramework" Version="3.2.0" />
- <PackageReference Include="coverlet.collector" Version="6.0.0">
+ <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.9.0" />
+ <PackageReference Include="MSTest.TestAdapter" Version="3.2.2" />
+ <PackageReference Include="MSTest.TestFramework" Version="3.2.2" />
+ <PackageReference Include="coverlet.collector" Version="6.0.1">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
  </PackageReference>

diff --git a/src/MigrationTools.ConsoleDataGenerator/MigrationTools.ConsoleDataGenerator.csproj b/src/MigrationTools.ConsoleDataGenerator/MigrationTools.ConsoleDataGenerator.csproj
@@ -16,7 +16,7 @@
  </PropertyGroup>
 
  <ItemGroup>
- <PackageReference Include="YamlDotNet" Version="15.1.0" />
+ <PackageReference Include="YamlDotNet" Version="15.1.2" />
  </ItemGroup>
 
  <ItemGroup>

diff --git a/src/MigrationTools.Host.Tests/MigrationTools.Host.Tests.csproj b/src/MigrationTools.Host.Tests/MigrationTools.Host.Tests.csproj
@@ -16,10 +16,10 @@
  </ItemGroup>
 
  <ItemGroup>
- <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
- <PackageReference Include="MSTest.TestAdapter" Version="3.2.0" />
- <PackageReference Include="MSTest.TestFramework" Version="3.2.0" />
- <PackageReference Include="coverlet.collector" Version="6.0.0">
+ <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.9.0" />
+ <PackageReference Include="MSTest.TestAdapter" Version="3.2.2" />
+ <PackageReference Include="MSTest.TestFramework" Version="3.2.2" />
+ <PackageReference Include="coverlet.collector" Version="6.0.1">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
  </PackageReference>

diff --git a/src/MigrationTools.Host/MigrationTools.Host.csproj b/src/MigrationTools.Host/MigrationTools.Host.csproj
@@ -14,7 +14,7 @@
 
  <ItemGroup>
  <PackageReference Include="CommandLineParser" Version="2.9.1" />
- <PackageReference Include="GitInfo" Version="3.3.3">
+ <PackageReference Include="GitInfo" Version="3.3.4">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
  </PackageReference>
@@ -23,7 +23,7 @@
  <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
  <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
  <PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" Version="8.0.0" />
- <PackageReference Include="NuGet.Protocol" Version="6.8.0" />
+ <PackageReference Include="NuGet.Protocol" Version="6.9.1" />
  <PackageReference Include="Serilog" Version="3.1.1" />
  <PackageReference Include="Serilog.Enrichers.Environment" Version="2.3.0" />
  <PackageReference Include="Serilog.Enrichers.Process" Version="2.0.2" />

diff --git a/src/MigrationTools.Integration.Tests/MigrationTools.Integration.Tests.csproj b/src/MigrationTools.Integration.Tests/MigrationTools.Integration.Tests.csproj
@@ -9,11 +9,11 @@
  <ItemGroup>
  <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
  <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="8.0.0" />
- <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
+ <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.9.0" />
  <PackageReference Include="Microsoft.TeamFoundationServer.ExtendedClient" Version="16.205.1" />
- <PackageReference Include="MSTest.TestAdapter" Version="3.2.0" />
- <PackageReference Include="MSTest.TestFramework" Version="3.2.0" />
- <PackageReference Include="coverlet.collector" Version="6.0.0">
+ <PackageReference Include="MSTest.TestAdapter" Version="3.2.2" />
+ <PackageReference Include="MSTest.TestFramework" Version="3.2.2" />
+ <PackageReference Include="coverlet.collector" Version="6.0.1">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
  </PackageReference>

diff --git a/src/MigrationTools.Tests/MigrationTools.Tests.csproj b/src/MigrationTools.Tests/MigrationTools.Tests.csproj
@@ -9,11 +9,11 @@
  <ItemGroup>
  <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
  <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="8.0.0" />
- <PackageReference Include="Microsoft.Extensions.Options" Version="8.0.1" />
- <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
- <PackageReference Include="MSTest.TestAdapter" Version="3.2.0" />
- <PackageReference Include="MSTest.TestFramework" Version="3.2.0" />
- <PackageReference Include="coverlet.collector" Version="6.0.0">
+ <PackageReference Include="Microsoft.Extensions.Options" Version="8.0.2" />
+ <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.9.0" />
+ <PackageReference Include="MSTest.TestAdapter" Version="3.2.2" />
+ <PackageReference Include="MSTest.TestFramework" Version="3.2.2" />
+ <PackageReference Include="coverlet.collector" Version="6.0.1">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
  </PackageReference>

diff --git a/src/MigrationTools/MigrationTools.csproj b/src/MigrationTools/MigrationTools.csproj
@@ -23,7 +23,7 @@
  <PackageReference Include="Microsoft.ApplicationInsights" Version="2.22.0" />
  <PackageReference Include="Microsoft.Extensions.Configuration" Version="8.0.0" />
  <PackageReference Include="Microsoft.Extensions.Logging" Version="8.0.0" />
- <PackageReference Include="Microsoft.Extensions.Options" Version="8.0.1" />
+ <PackageReference Include="Microsoft.Extensions.Options" Version="8.0.2" />
  <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
  <PackageReference Include="Microsoft.IdentityModel.Clients.ActiveDirectory" Version="5.3.0" />
  <PackageReference Include="Microsoft.VisualStudio.Services.Client" Version="16.205.1" />