Skip to content

Commit 3354f58

Browse files
MrHinshMrHinsh
committed
📝 docs(docs): update links and improve descriptions
- update link for 'Getting started' section in list.html - add page content section in list.html - improve sidebar logic for displaying short titles 📝 docs(docs): enhance documentation and structure - add description to 'Getting Started with Azure DevOps Migration Tools' - create new version control documentation for Git and TFVC 📝 docs(setup): restructure setup documentation - add descriptions and short titles to setup pages - separate installation and permissions into their own directories - update aliases and redirect paths for setup documentation
1 parent f8efe6a commit 3354f58

File tree

9 files changed

+95
-50
lines changed

9 files changed

+95
-50
lines changed

‎module/layouts/docs/list.html‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,8 +84,13 @@ <h5 class="card-title">
8484
</div>
8585
{{ end }}
8686

87+
{{/* Page content */}}
88+
<div class="docs-body">
89+
{{ .Content }}
90+
</div>
91+
8792
{{/* Getting started section */}}
88-
{{ $gettingStarted := .Site.GetPage "/docs/getstarted" }}
93+
{{ $gettingStarted := .Site.GetPage "/docs/get-started/getting-started/" }}
8994
{{ if $gettingStarted }}
9095
<div class="docs-getting-started mt-5">
9196
<div class="alert alert-primary" role="alert">

‎module/layouts/partials/docs/sidebar-tree.html‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,11 @@
1717
{{/* Section headers for main categories at level 0 */}}
1818
{{ if eq $level 0 }}
1919
<div class="sidebar-section-title">
20-
{{ .Title }}
20+
{{ if .Params.short_title }}
21+
{{ .Params.short_title }}
22+
{{ else }}
23+
{{ .Title }}
24+
{{ end }}
2125
</div>
2226
{{ else }}
2327
{{/* Regular navigation links for deeper levels */}}

‎site/content/docs/get-started/_index.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
---
22
title: Getting Started with Azure DevOps Migration Tools
3+
description: |
4+
If you want to perform a bulk edit or a migration then you need to start here. This tool has been tested on updating from 100 to 250,000 work items by its users.
5+
Watch the Video Overview to get started in 30 minutes. This tool is complicated and it's not always easy to discover what you need to do.
36
short_title: Getting Started
47
weight: 1
58
aliases:
6-
- /getstarted/
9+
- /getstarted/
710
date: 2025-06-24T12:07:31Z
8-
911
---
10-

‎site/content/docs/get-started/getting-started/index.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
---
2-
title: 'Tutorial: Get started with the Azure DevOps Migration Tools'
2+
title: "Tutorial: Get started with the Azure DevOps Migration Tools"
33
short_title: Get Started
4-
discussionId:
5-
redirect_from:
6-
- /getting-started/
4+
discussionId:
5+
weight: 1
6+
aliases:
7+
- /getting-started/
78
date: 2025-06-24T12:07:31Z
8-
99
---
10+
1011
If you want to perform a bulk edit or a migration then you need to start here. This tool has been tested on updating from 100 to 250,000 work items by its users.
1112

1213
Watch the [Video Overview](https://youtu.be/RCJsST0xBCE) to get started in 30 minutes. This tool is complicated and it's not always easy to discover what you need to do.

‎site/content/docs/get-started/version-control/index.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: "Getting Started with Git and TFVC Version Control"
3+
short_title: Version Control
4+
description: |
5+
While we do not migrate source control for you, we do have tools to maintain the links between work items and source code.
6+
discussionId:
7+
aliases:
8+
- /version-control/
9+
date: 2025-06-24T12:07:31Z
10+
---
11+
12+
While we do not migrate source control for you, we do have tools to maintain the links between work items and source code.
13+
14+
## Git Version Control (GIT)
15+
16+
While we do not have any tools to migrate Git repositories, we do have tools to maintain the links between work items and source code. This is done by using the [TfsGitRepositoryTool](/_reference/reference.tools.tfsgitrepositorytool.md) configuration section.
17+
18+
As long as the Git repos exist and have the same name, just enabling [TfsGitRepositoryTool](/_reference/reference.tools.tfsgitrepositorytool.md) is enough. If you have diferent names for the repositories, you can use the [TfsGitRepositoryTool](/_reference/reference.tools.tfsgitrepositorytool.md) configuration section to map the source repository to the target repository.
19+
20+
## Team Foundation Version Control (TFVC)
21+
22+
Although TFVC has been depreciated for quite some time there are still many folks that use it. We don't support migrating it directly, but if you have migrated your TFVC repository to Git, you can use the [TfsChangesetMappingTool](/_reference/reference.tools.tfschangesetmappingtool.md) to maintain the links between work items and changesets.
23+
24+
Azure DevOps Migration Tools enable migrating work item changesets with cross project links from TFVC or git.
25+
26+
### Migrate Changesets from TFVC to Git
27+
28+
For a successful migration of work items changesets from TFVC to Git you need a mapping file with ChangeSetId - CommitId values that you can had to the [TfsChangesetMappingTool](/_reference/reference.tools.tfschangesetmappingtool.md). If you
29+
have migrated your TFVC repository with [git-tfs](https://github.com/git-tfs/git-tfs) you can generate this file by using the following
30+
[command](https://github.com/git-tfs/git-tfs/blob/master/doc/commands/exportmap.md). Then follow the documentation on [TfsChangesetMappingTool](/_reference/reference.tools.tfschangesetmappingtool.md) to configure the tool with this file.
31+
32+
#### Migrate Changesets from TFVC to Git with external project links
33+
34+
If your changesets contain cross project links make sure to update the "GitRepoMapping" configuration section.
35+
36+
##### Use Cases
37+
38+
Lets assume you have Project A with a TFVC repository and a Project B with Work Items, which changesets link to Project A.
39+
You wish to migrate Project A to a Git Repository in Project C and move the work Items including changesets from Project B to Project C and all
40+
changesets from Project B needs to move to the Git Repository of Project C. To achieve this follow the steps:
41+
42+
1. Migrate your repository and make sure to create the mapping file.
43+
2. Edit the configuration file with following settings in [TfsGitRepositoryTool](/_reference/reference.tools.tfsgitrepositorytool.md):
44+
45+
"GitRepoMapping": {"A" :"C","B" :"C"}
46+
47+
3. Run the migration with configuration file that contain set in [TfsChangesetMappingTool](/_reference/reference.tools.tfschangesetmappingtool.md).
48+
49+
"ChangeSetMappingFile": "C:\\git-tfs\\ChangeSetId-to-CommitId\\{mappingFile}",

‎site/content/docs/setup/_index.md‎

Lines changed: 5 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,10 @@
11
---
22
title: Setting up the Azure DevOps Migration Tools
3-
discussionId:
3+
description: |
4+
If you want to perform a bulk edit or a migration then you need to start here. This tool has been tested on updating from 100 to 250,000 work items by its users.
5+
Watch the Video Overview to get started in 30 minutes. This tool is complicated and it's not always easy to discover what you need to do.
6+
short_title: Setting Up
7+
discussionId:
48
weight: 2
59
date: 2025-06-24T12:07:31Z
6-
710
---
8-
To use these tools you will need to install them and configure your target environment (TFS or Azure DevOps). The following pages will guide you through the process:
9-
10-
1. [Installation](installation.md)
11-
12-
The tools are run using `devopsmigration` from the command line. You can use the `--help` option to see the available commands.
13-
14-
```shell
15-
devopsmigration --help
16-
```
17-
18-
2. [Permissions](permissions.md)
19-
20-
The tools require specific permissions on TFS or Azure DevOps to be able to run. This page will guide you through the minimum permissions required to run the tools.
21-
22-
3. [ReflectedWorkItemId](reflectedworkitemid.md)
23-
24-
We use a field on the work item to track the migration of work items. This field is always referred to in the docs as `ReflectedWorkItemId` and is used to track the work item in the target. It enables the ability to resume migrations as well as to be able to scope the work items based on a query and have multiple runs overlap.
25-
26-
1. [Getting Started](../getstarted/)

site/content/docs/setup/installation.md renamed to site/content/docs/setup/installation/index.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
---
2-
title: Installation
3-
layout: page
4-
pageType: index
5-
toc: true
6-
pageStatus: published
2+
title: Install Azure DevOps Migration Tools on Windows
3+
description: |
4+
Install the Azure DevOps Migration Tools on Windows.
5+
These tools are available as a portable application and can be installed in a number of ways, including manually from a zip.
6+
short_title: Installation
77
discussionId:
8-
redirect_from:
8+
aliases:
99
- /installation/
1010
- /setup/installation/
1111
---

site/content/docs/setup/permissions.md renamed to site/content/docs/setup/permissions/index.md

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
---
22
title: Permissions
3-
layout: page
4-
pageType: index
5-
toc: true
6-
pageStatus: published
7-
discussionId:
8-
redirect_from:
3+
short_title: Permissions
4+
description: |
5+
The current permissions are governed by the requirements of the TFS Client Object Model from Microsoft.
6+
While Microsoft announced the deprecation of the WIT and Test Client OM in 2020, it remains the only consistent method for interacting with versions of TFS from 2010 to 2018.
7+
date: 2025-06-24T12:07:31Z
8+
discussionId:
9+
aliases:
910
- /permissions/
1011
---
1112

@@ -53,4 +54,4 @@ You can use the following command to do this:
5354
tfssecurity /g+ "Project Collection Service Accounts" n:domainusername ALLOW /server:http://myserver:8080/tfs
5455
```
5556

56-
This step is not required for Azure DevOps Service targets, as `tfssecurity` is not available in that environment.
57+
This step is not required for Azure DevOps Service targets, as `tfssecurity` is not available in that environment.

‎site/content/docs/setup/reflectedworkitemid/index.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
---
22
title: ReflectedWorkItemId
3-
layout: page
4-
pageType: index
5-
pageStatus: published
3+
short_title: ReflectedWorkItemId
4+
description: |
5+
The Azure DevOps migrations Tools has no internal state, and uses a field on the work item to track the migration of work items. This field is always referred to in the docs as `ReflectedWorkItemId` and is used to track the work item in the target.
66
redirect_from:
7-
- /Reference/ReflectedWorkItemId/
8-
- /server-configuration/
7+
- /Reference/ReflectedWorkItemId/
8+
- /server-configuration/
99
date: 2025-06-24T12:07:31Z
10-
1110
---
11+
1212
The Azure DevOps migrations Tools has no internal state, and uses a field on the work item to track the migration of work items. This field is always referred to in the docs as `ReflectedWorkItemId` and is used to track the work item in the target. It enables the ability to resume migrations as well as to be able to scope the work items based on a query and have multiple runs overlap.
1313

1414
Se below how to add the `ReflectedWorkItemId` to your target project as its different for Azure DevOps, TFS, and if you imported your Collection from TFS to Azure DevOps.

0 commit comments

Comments
 (0)