Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix: Remove old projects, format and organize markdown #287

Merged
merged 9 commits into from
Nov 22, 2024
Merged

Fix: Remove old projects, format and organize markdown #287

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
fd75d40
fix(sln): remove unreferenced Migration.Tool.Model project
seangwright Nov 6, 2024
ca3ba19
docs(README): simplify/re-organize content
seangwright Nov 6, 2024
b352f47
docs(CLI): format README
seangwright Nov 6, 2024
f69f17a
docs(CLI): remove typo
seangwright Nov 6, 2024
c2c473b
docs(sln): format, restructure, grammar/typos
seangwright Nov 6, 2024
a64aaa5
build(github): issue template format, instructions
seangwright Nov 6, 2024
737b82c
docs(README): add links to migration guides
seangwright Nov 6, 2024
a2c6606
Merge branch 'master' into fix/remove-old-docs-and-projects
seangwright Nov 15, 2024
254714b
Merge branch 'rls/v1.6.0' into fix/remove-old-docs-and-projects
seangwright Nov 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions .github/ISSUE_TEMPLATE/bug_report.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,16 @@
---
name: Bug report
about: Create a report to help us improve

---

### Brief bug description

What went wrong?

## Output logs

Please include the command line output log file and migration protocol generated for your `Migration.Tool.CLI.exe migrate` command.

### Repro steps

1. Go to '...'
Expand All @@ -21,9 +24,9 @@ What is the correct behavior?

### Test environment

- Platform/OS: [e.g. .NET Core 2.1, iOS]
- Browser [e.g. chrome, safari]
- Version [e.g. 22]
- Platform/OS: [e.g. .NET Core 2.1, iOS]
- Browser [e.g. chrome, safari]
- Version [e.g. 22]

### Additional context

Expand Down
24 changes: 8 additions & 16 deletions Migration.Tool.CLI/MIGRATION_PROTOCOL_REFERENCE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,15 @@
## Migration Protocol Reference
# Migration Protocol Reference

Running the `Migration.Tool.CLI.exe migrate` command (
see [`Migration.Tool.CLI/README.md`](/Migration.Tool.CLI/README.md)) generates a **migration protocol file**. The
protocol provides information about the result of the migration, lists required manual steps, etc.

You can find the protocol file in the location specified by
the `Settings.MigrationProtocolPath` [configuration option](/Migration.Tool.CLI/README.md#Configuration).
You can find the protocol file path in the `.\Migration.Tool.CLI\appsettings.json` file under the [`MigrationProtocolPath` configuration option](/Migration.Tool.CLI/README.md#Configuration).
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We usually try to write the documentation in a task-oriented style. Although finding the protocol file path is a task we'd like the user to achieve, it is not the primary goal, the goal we'd like them to achieve is to find the protocol file.


## Common Migration Protocol Warnings & Errors

| Message ReferenceName | Severity | Description |
|-------------------------------------------------------------|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ----------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- |
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The table syntax is broken by adding a column without a heading.

Suggested change
| ----------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- |
| ----------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| BulkCopyColumnMismatch | Error | For performance optimization, the migration transfers certain objects using bulk SQL queries. The columns in the related database tables must match on the source and target. The migration attempts to discard data from extra columns on the source.<br /><br />**Fix**: Review the tables for customizations on the source instance and revert/update the schema to match the default Kentico Xperience 13 state. |
| CmsClass_CmsRootClassTypeSkip | Information | 'CMS.Root' is a special system page type and is not supported for migration.<br /><br />**Fix**: No actions required. Xperience by Kentico contains a root page type by default. |
| CmsTree_TreeIsLinkFromDifferentSite | Warning | The content tree contains a page that is linked from a different site. Linked pages from other sites are not supported for migration (Xperience by Kentico currently does not allow multiple sites). <br /><br />**Fix**: Remove the linked page on the source instance or create a copy that is not linked from a different site. |
Expand All @@ -21,25 +20,18 @@ the `Settings.MigrationProtocolPath` [configuration option](/Migration.Tool.CLI/
| DbConstraintBroken | Error | General error message indicating that the target database cannot hold migrated data, due to duplicate values in unique columns (e.g., primary keys) or due to a missing dependency.<br /><br />**Fix**: Manually migrate the object (specified object by the ID in the message), or check if dependencies required by the object were successfully migrated. |
| EntityExplicitlyExcludedByCodeName | Warning | The object is excluded via the `Settings.EntityConfigurations.<object table name>.ExcludeCodeNames` configuration option.<br /><br />**Fix**: If you wish to migrate the object, remove the given code name from the configuration. |
| ErrorSavingTargetInstance | Error | A general error that prevents data from being saved in the target Xperience by Kentico database. For example, can be caused by a database timeout or temporary outage. |
| FailedToCreateTargetInstance | Error | General error when the creation of the target entity failed. Can be caused by a problem with the source data or by an error in the Migration tool.<br /><br />**Fix**: Check if the related source data is compatible with the target or report a Migration tool issue. |
| FailedToCreateTargetInstance | Error | General error when the creation of the target entity failed. Can be caused by a problem with the source data or by an error in the Migration tool.<br /><br />**Fix**: Check if the related source data is compatible with the target or report a Migration tool issue. |
| FailedToUpdateTargetInstance / FailedToUpdateTargetInstance | Error | General error when updating / inserting an object on the target instance.<br /><br />**Fix**: Depends on the details in the error message. Can have various causes, such as an interrupted database connection or malformed/incorrect data. |
| FormComponentNotSupportedInLegacyMode | Warning | Logged when Page Builder content on the source instance contains a property using a form component that is not supported by the Page Builder legacy mode in Xperience by Kentico. |
| InvalidSourceData | Warning | The source instance is missing required data or data is malformed.<br /><br />**Fix**: Review the message details and try to look for differences between the source and target database schema. |
| LinkedDataAlreadyMaterializedInTargetInstance | Warning | A linked page already exists in the target instance and an update is not possible.<br /><br />**Fix**: No actions required. The update is probably not required. |
| MediaFileIsMissingOnSourceFilesystem | Error | Occurs when a media file is missing from the source project's file system and the `Settings.MigrateOnlyMediaFileInfo` configuration option is `false`.<br /><br />**Fix**: Manually migrate the source media file to the target instance's file system. | |
| MissingConfiguration | Error | The migrate command is missing required configuration.<br /><br />**Fix**: Add required configuration according to the error message. See [`Migration.Tool.CLI/README.md`](/Migration.Tool.CLI/README.md). |
| MediaFileIsMissingOnSourceFilesystem | Error | Occurs when a media file is missing from the source project's file system and the `Settings.MigrateOnlyMediaFileInfo` configuration option is `false`.<br /><br />**Fix**: Manually migrate the source media file to the target instance's file system. | |
| MissingConfiguration | Error | The migrate command is missing required configuration.<br /><br />**Fix**: Add required configuration according to the error message. See [`Migration.Tool.CLI/README.md`](/Migration.Tool.CLI/README.md). |
| MissingRequiredDependency | Error | An object from the source is missing a dependency required on the target instance.<br /><br />**Fix**: Add the missing dependency on the source instance or delete the object completely. |
| NotCurrentlySupportedSkip | Warning | Xperience by Kentico currently does not support all types of objects from Kentico Xperience 13, so they cannot be migrated via the tool. Support may be added in future versions of Xperience by Kentico and the Migration tool.<br /><br />**Fix**: Implement custom migration. |
| NotCurrentlySupportedSkip | Warning | Xperience by Kentico currently does not support all types of objects from Kentico Xperience 13, so they cannot be migrated via the tool. Support may be added in future versions of Xperience by Kentico and the Migration tool.<br /><br />**Fix**: Implement custom migration. |
| NotSupportedSkip | Information | Occurs for data that is not supported in Xperience by Kentico. Migration is not supported, and is not planned for upcoming versions.<br /><br />**Fix**: Implement custom migration. |
| SourceEntityIsNull | Error | Probably an error while loading source data. Can be caused by malformed source data or by an error in the Migration tool.**Fix**: Check the related source data. If everything looks correct, report a Migration tool issue. |
| SourceEntityIsNull | Error | Probably an error while loading source data. Can be caused by malformed source data or by an error in the Migration tool.**Fix**: Check the related source data. If everything looks correct, report a Migration tool issue. |
| SourcePageIsNotPublished | Warning | Only published pages are included in the migration. This warning occurs when a page on the source is not published.<br /><br />**Fix**: Publish all pages that you wish to migrate in the source instance. |
| SourceValueIsRequired | Error | A source object instance has a missing value in a required field.<br /><br />**Fix**: Review the message and fill in the missing value on the source instance. |
| TemporaryAttachmentMigrationIsNotSupported | Warning | Temporary page attachments are created when a file upload is not finished correctly. The migration does not include temporary attachments.<br /><br />**Fix**: No actions required. If you wish to migrate the file, re-upload the attachment on the source instance to create a standard attachment. |
| ValueTruncationSkip | Error | Occurs when a target database field has a lower allowed size than the source database field.<br /><br />**Fix**: Truncate the value to the required size on the source instance, or omit the value completely. |

## Submit issues

See [`CONTRIBUTING.md`](/CONTRIBUTING.md).

When submitting issues, please provide all available information about the problem or error. If possible, include the
command line output log file and migration protocol generated for your `Migration.Tool.CLI.exe migrate` command.
Loading