Documentation clarification

[denravonska]

Hi

I've been using this tool to migrate from one organization to another and bumped into some confusing points in the documentation that could need some love.

Node structure mapping

According to the TfsNodeStructure documentation we only need to specify a dictionary type for the mappings:

{
  "$type": "TfsNodeStructureOptions",
  "Enabled": true,
  "NodeBasePaths": null,
  "AreaMaps": {
    "$type": "Dictionary`2"           <-------
  },
  "IterationMaps": {
    "$type": "Dictionary`2"          <-------
  },
  "ShouldCreateMissingRevisionPaths": true,
  "ReplicateAllExistingNodes": false
}

This triggered a type mismatch error for me (the error has scrolled way gone by now). What worked for my, simple, clone operation was:

  "CommonEnrichersConfig": [
	{
		"$type": "TfsNodeStructureOptions",
		"RefName": "TfsNodeStructure",
		"Enabled": true,
		"PrefixProjectToNodes": false,
		"NodeBasePaths": [],
		"ShouldCreateMissingRevisionPaths": true,
		"ReplicateAllExistingNodes": true,
		"AreaMaps": {
			"^FROM_PROJECT([\\\\]?.*)$": "TO_PROJECT$1",       <-----
		},
		"IterationMaps": {
			"^FROM_PROJECT([\\\\]?.*)$": "TO_PROJECT$1",         <-----
		}
	}
  ],

This also solved a somewhat confusing error message about "FROM_PROJECT\Area" not being anchored in the target projected even though I had a specific mapping for that. Probably a skill issue on my end.

Automatic area/iteration creation

The node structure documentation also has this note:

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!

I interpreted that as the iteration paths and areas must exist on the target project prior to starting the migration. Once I got everything rolling it turned out that that was not the case and the tool happily created the iterations for me and migrated the work items.

[MrHinsh]

Yea the docs are generated and I have not yet figured out how to get it not to put that in there!

Ive got a new version of the configuration coming down the pipe and the samples will instead look like:

{
  "MigrationTools": {
    "CommonTools": {
      "TfsNodeStructureTool": {
        "Enabled": true,
        "NodeBasePaths": null,
        "AreaMaps": {
          "^migrationSource1([\\\\]?.*)$": "MigrationTest5$1"
        },
        "IterationMaps": {
          "^migrationSource1([\\\\]?.*)$": "MigrationTest5$1"
        },
        "ShouldCreateMissingRevisionPaths": true,
        "ReplicateAllExistingNodes": true
      }
    }
  }
}

I'm there for platform, and for docs rebuild.. but init is still disabled as it relies on the old version... I don't want to ship without init.

[MrHinsh]

p.s. This is a major bump and will also enable being able to override almost anything with Environment variable or with the command line...

I currently set $Env:MigrationTools__Target__AccessToken and then don't need to set it in the config...

[MrHinsh]

It will also allow anyone to go look up the defaults in the appsettings.json file.