|
1 | | -# migrate-yfiles-app |
2 | | -Javascript toolchain that helps in migrating yFiles for HTML 2.1 apps to the yFiles for HTML 2.2 API |
3 | | - |
4 | | -# Usage |
5 | | -1. Run `npm install` to install the dependencies. |
6 | | -2. Specify the input (`contentSrc`) and output (`contentDest`) folder in the gruntfile. |
7 | | -3. Run `grunt` to migrate your files from yFiles for HTML 2.1 to yFiles for HTML 2.2. |
8 | | - |
9 | | -# Notes |
10 | | -Please review the migrated files after the process. The migration tool will automatically convert API calls from 2.1 to 2.2. |
11 | | -Afterwards you will find many yFiles API calls to be migrated automatically. Usually, you will also find `TODO: Migration: ...` |
12 | | -annotations in the output files. These occurences need a manual review because the tool was not able to convert it automatically. |
13 | | -This may be due to missing type information or due to incompatible API changes. |
| 1 | +# yFiles for HTML migration tool |
| 2 | +Migrate outdated yFiles for HTML code to **yFiles for HTML 2.3**. |
| 3 | + |
| 4 | +The source of this tool is available at [GitHub](https://github.com/yWorks/migrate-yfiles-app). |
| 5 | + |
| 6 | +## Usage |
| 7 | + |
| 8 | +1. Install the migration tool globally: |
| 9 | + |
| 10 | + `npm install -g @yworks/migrate-yfiles-app` |
| 11 | + |
| 12 | +2. Migrate your project: |
| 13 | + |
| 14 | + `migrate-yfiles-app --src=./src --dest=./src-migrated --from=1.3` |
| 15 | + |
| 16 | +The output of the tool includes code locations in a simple format that will be recognized by most IDEs |
| 17 | +(e.g. VS Code, Webstorm), so you can click on output lines to migrate the corresponding code manually. |
| 18 | + |
| 19 | +## Incremental Mode |
| 20 | + |
| 21 | +The tool offers an incremental mode where it will not actually transform your files, but will only output |
| 22 | +messages that describe what has to be changed at which location. This allows you to migrate your app iteratively, until no such messages are printed anymore. The messages usually take the following form: |
| 23 | + |
| 24 | +``` |
| 25 | +The thing 'oldThing' has been changed to 'newThing' in version <versionNumber>. [additional information here.] |
| 26 | + at <absolute path to file, including line and column numbers> |
| 27 | +``` |
| 28 | + |
| 29 | +We recommend running the tool once in non-incremental mode to get the automatic code changes, and afterwards running |
| 30 | +it in incremental mode to migrate the things that could not be handled automatically. |
| 31 | + |
| 32 | +Messages can also be suppressed by putting a comment with the content `@migration-ignore` above the line where the message occurs. |
| 33 | +This is useful if you are sure that the code is already correct. |
| 34 | + |
| 35 | +## Command Line Arguments |
| 36 | + |
| 37 | +### Required Arguments |
| 38 | + |
| 39 | +| | | | |
| 40 | +| --- | --- | --- | |
| 41 | +| `-f` | `--from` | The version of yFiles for HTML from which to migrate. Available options: 1.3, 1.4, 2.0, 2.1 | |
| 42 | +| `-s` | `--src` | The input file/directory to be transformed. | |
| 43 | +| `-d` | `--dest` | The destination directory where all transformed files will be written to. This has to be empty unless the `--incremental` or `--force` options are specified. | |
| 44 | + |
| 45 | + |
| 46 | +### Optional Arguments |
| 47 | +| | | | |
| 48 | +| --- | --- | --- | |
| 49 | +| `-i` | `--incremental` | Run the migration tool in [incremental mode](#incremental-mode). | |
| 50 | +| `-e` | `--extensions` | Which file extensions to transform. Default: `.js` and `.ts`| |
| 51 | +| `-l` | `--singleline` | Write log messages in a single line instead of printing the source location to a second line. | |
| 52 | +| `-v` | `--verbose` | Log verbose jscodeshift messages | |
| 53 | +| | `--force` | Overwrite files in the destination directory. |
| 54 | +| `-nc` | `--nocolor` | Don't colorize the log messages. | |
| 55 | +| | `--version` | Show the version number. | |
| 56 | +| | `--help` | Show help. | |
| 57 | +| `-t` | `--transforms` | Which transforms to apply. | |
| 58 | + |
| 59 | +## Logging Debug Messages |
| 60 | + |
| 61 | +The migration tool uses the [npm debug module](https://www.npmjs.com/package/debug) to log debugging information in individual transforms. To enable all debug messages, set the `DEBUG` environment variable to `migrate-yfiles-app:*`. This will output all migration tool debug messages. To restrict the debug output to a specific |
| 62 | +feature/transform, use the corresponding specifier, e.g. `DEBUG=migrate-yfiles-app:toEs6Class`. |
| 63 | + |
| 64 | +## VS Code Problem Matcher |
| 65 | + |
| 66 | +Navigating possible problems detected by the migration tool can be facilitated using a problem matcher in VS Code. |
| 67 | +The messages are summarized by file in the problems panel, and the corresponding sections are highlighted in |
| 68 | +the source code: |
| 69 | + |
| 70 | + |
| 71 | + |
| 72 | +To enable problem matching in VS Code, add a task with the [matcher definition](https://code.visualstudio.com/docs/editor/tasks#_defining-a-problem-matcher) to your [`.vscode/tasks.json`](https://code.visualstudio.com/docs/editor/tasks) file: |
| 73 | + |
| 74 | +```json |
| 75 | +{ |
| 76 | + "version": "2.0.0", |
| 77 | + "tasks": [ |
| 78 | + { |
| 79 | + "label": "Run yFiles migration tool", |
| 80 | + "type": "shell", |
| 81 | + "command": "migrate-yfiles-app", |
| 82 | + "args": [ |
| 83 | + "--src=app-src", |
| 84 | + "--dest=dest/", |
| 85 | + "--from=1.3", |
| 86 | + "--force", |
| 87 | + "--singleline" |
| 88 | + ], |
| 89 | + "problemMatcher": { |
| 90 | + "fileLocation": ["absolute"], |
| 91 | + "pattern": { |
| 92 | + "regexp": "^(.*?):(\\d+):(\\d+)\\s-\\s(.*)$", |
| 93 | + "file": 1, |
| 94 | + "line": 2, |
| 95 | + "column": 3, |
| 96 | + "message": 4 |
| 97 | + } |
| 98 | + }, |
| 99 | + "presentation": { |
| 100 | + "clear": true, |
| 101 | + "showReuseMessage": false |
| 102 | + } |
| 103 | + } |
| 104 | + ] |
| 105 | +} |
| 106 | +``` |
0 commit comments