Introduction

This repo is used to migrate existing V2 docset to V3.

Prerequisites

• install nodejs
• run npm install in the repo to install npm packages

Prepare local doc repo for migration

Use git clone {gitRepoUrl} to clone the repo for migration, the following files are used during migration:

• .openpublishing.publish.config.json
• docfx.json
• .openpublishing.redirection.json (if presents)

Migrate script usage

Run npm rum migrate -- -r {gitRepoUrl} -t {op-build-user-token} [-d {directory}] [-o {output-directory}] [-b {branch}] [-l {log-path}]

• {gitRepoUrl}: The git repository url(it should be https) e.g. https://github.com/MicrosoftDocs/azure-docs-pr (required)
• {op-build-user-token}: Token used for invoking OPS APIs. Check hereto get a long period op build token for api request (required)
• {directory}: The local git worktree directory(optional, will use current directory if not specified).
• {output-directory}: Output directory for the generated docfx.yml, it will be the same as {directory} if it's not set.
• {branch}: The git branch to migrate(optional)
• {log-path}: The path of the log file(optional) (will only log to console if it's set to console-only)
• {env}: The repository environment, can be prod, sandbox, internal or perf(optional)
• {user-cache}: Add git-hub config property to config

Check Migration Result

• A docfx.yml will be generated inside the {output-directory}
• Necessary changes will be made in the worktree(TBD)

Project Structure

The general idea is:

1. load a default docfx.yml template
2. load necessary configurations from from OPS server & local, including
   • .openpublishing.publish.config.json
   • docfx.json configs
   • .openpublishing.redirection.json
3. calculate and fill in each property properly (and only support single docset case)

Running Test

The test framework used isMocha. Run npm test or npm t to run all the tests. Run with addition -- -w/--watch to run it in watch mode