diff --git a/.editorconfig b/.editorconfig
index a73a2f48..f649bc7f 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -1,80 +1,347 @@
+# Severity levels of analyzers https://docs.microsoft.com/en-us/visualstudio/code-quality/roslyn-analyzers-overview?view=vs-2019#severity-levels-of-analyzers
+
root = true
-[*]
-# Most of the standard properties are supported
-max_line_length = 200
-charset = utf-8
-end_of_line = crlf
-trim_trailing_whitespace = true
-insert_final_newline = false
-indent_style = space
-indent_size = 4
-
-# Microsoft .NET properties
-csharp_new_line_before_members_in_object_initializers = true
-csharp_preferred_modifier_order = public, private, protected, internal, new, static, abstract, virtual, sealed, readonly, override, extern, unsafe, volatile, async, required:suggestion
-csharp_style_var_elsewhere = true:suggestion
-csharp_style_var_for_built_in_types = true:suggestion
-csharp_style_var_when_type_is_apparent = true:suggestion
-csharp_using_directive_placement = inside_namespace:silent
-dotnet_naming_rule.private_constants_rule.import_to_resharper = as_predefined
-dotnet_naming_rule.private_constants_rule.severity = warning
-dotnet_naming_rule.private_constants_rule.style = all_upper_style
-dotnet_naming_rule.private_constants_rule.symbols = private_constants_symbols
-dotnet_naming_rule.unity_serialized_field_rule.import_to_resharper = True
-dotnet_naming_rule.unity_serialized_field_rule.resharper_description = Unity serialized field
-dotnet_naming_rule.unity_serialized_field_rule.resharper_guid = 5f0fdb63-c892-4d2c-9324-15c80b22a7ef
-dotnet_naming_rule.unity_serialized_field_rule.severity = warning
-dotnet_naming_rule.unity_serialized_field_rule.style = lower_camel_case_style
-dotnet_naming_rule.unity_serialized_field_rule.symbols = unity_serialized_field_symbols
-dotnet_naming_style.all_upper_style.capitalization = all_upper
-dotnet_naming_style.all_upper_style.word_separator = _
-dotnet_naming_style.lower_camel_case_style.capitalization = camel_case
-dotnet_naming_symbols.private_constants_symbols.applicable_accessibilities = private
-dotnet_naming_symbols.private_constants_symbols.applicable_kinds = field
-dotnet_naming_symbols.private_constants_symbols.required_modifiers = const
-dotnet_naming_symbols.unity_serialized_field_symbols.applicable_accessibilities = *
-dotnet_naming_symbols.unity_serialized_field_symbols.applicable_kinds =
-dotnet_naming_symbols.unity_serialized_field_symbols.resharper_applicable_kinds = unity_serialised_field
-dotnet_naming_symbols.unity_serialized_field_symbols.resharper_required_modifiers = instance
-dotnet_style_parentheses_in_arithmetic_binary_operators = never_if_unnecessary:none
-dotnet_style_parentheses_in_other_binary_operators = always_for_clarity:none
-dotnet_style_parentheses_in_relational_binary_operators = never_if_unnecessary:none
-dotnet_style_predefined_type_for_locals_parameters_members = true:suggestion
-dotnet_style_predefined_type_for_member_access = true:suggestion
-dotnet_style_qualification_for_event = false:suggestion
-dotnet_style_qualification_for_field = false:suggestion
-dotnet_style_qualification_for_method = false:suggestion
-dotnet_style_qualification_for_property = false:suggestion
-dotnet_style_require_accessibility_modifiers = for_non_interface_members:suggestion
-
-# ReSharper properties
-resharper_autodetect_indent_settings = true
-resharper_csharp_allow_alias = false
-resharper_instance_members_qualify_declared_in =
-resharper_qualified_using_at_nested_scope = true
-resharper_use_indent_from_vs = false
-resharper_wrap_lines = true
-
-# ReSharper inspection severities
-resharper_arrange_redundant_parentheses_highlighting = hint
-resharper_arrange_this_qualifier_highlighting = hint
-resharper_arrange_type_member_modifiers_highlighting = hint
-resharper_arrange_type_modifiers_highlighting = hint
-resharper_built_in_type_reference_style_for_member_access_highlighting = hint
-resharper_built_in_type_reference_style_highlighting = hint
-resharper_redundant_base_qualifier_highlighting = warning
-resharper_suggest_var_or_type_built_in_types_highlighting = hint
-resharper_suggest_var_or_type_elsewhere_highlighting = hint
-resharper_suggest_var_or_type_simple_types_highlighting = hint
-resharper_web_config_module_not_resolved_highlighting = warning
-resharper_web_config_type_not_resolved_highlighting = warning
-resharper_web_config_wrong_module_highlighting = warning
-
-[{*.har,*.inputactions,*.jsb2,*.jsb3,*.json,.babelrc,.eslintrc,.stylelintrc,bowerrc,jest.config}]
-indent_style = space
-indent_size = 2
-
-[*.{appxmanifest,asax,ascx,aspx,axaml,build,c,c++,cc,cginc,compute,cp,cpp,cs,cshtml,cu,cuh,cxx,dtd,fx,fxh,h,hh,hlsl,hlsli,hlslinc,hpp,hxx,inc,inl,ino,ipp,master,mpp,mq4,mq5,mqh,nuspec,paml,razor,resw,resx,shader,skin,tpp,usf,ush,vb,xaml,xamlx,xoml,xsd}]
-indent_style = space
-indent_size = 4
-tab_width = 4
+
+[*.cs]
+end_of_line = crlf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+
+# Formatting Rules
+
+## IDE0055: Fix formatting
+dotnet_diagnostic.IDE0055.severity = error
+
+dotnet_sort_system_directives_first = true
+dotnet_separate_import_directive_groups = false
+
+## C# Formatting Rules https://docs.microsoft.com/en-us/dotnet/fundamentals/code-analysis/style-rules/formatting-rules
+
+### Newline options
+csharp_new_line_before_open_brace = all
+csharp_new_line_before_else = true
+csharp_new_line_before_catch = true
+csharp_new_line_before_finally = true
+csharp_new_line_before_members_in_object_initializers = true
+csharp_new_line_before_members_in_anonymous_types = true
+csharp_new_line_between_query_expression_clauses = true
+
+### Indentation options
+csharp_indent_case_contents = true
+csharp_indent_switch_labels = true
+csharp_indent_labels = one_less_than_current
+csharp_indent_block_contents = true
+csharp_indent_braces = false
+csharp_indent_case_contents_when_block = false
+
+### Spacing options
+csharp_space_after_cast = false
+csharp_space_after_keywords_in_control_flow_statements = true
+csharp_space_between_parentheses = false
+csharp_space_before_colon_in_inheritance_clause = true
+csharp_space_after_colon_in_inheritance_clause = true
+csharp_space_around_binary_operators = before_and_after
+csharp_space_between_method_declaration_parameter_list_parentheses = false
+csharp_space_between_method_declaration_empty_parameter_list_parentheses = false
+csharp_space_between_method_declaration_name_and_open_parenthesis = false
+csharp_space_between_method_call_parameter_list_parentheses = false
+csharp_space_between_method_call_empty_parameter_list_parentheses = false
+csharp_space_between_method_call_name_and_opening_parenthesis = false
+csharp_space_after_comma = true
+csharp_space_before_comma = false
+csharp_space_after_dot = false
+csharp_space_before_dot = false
+csharp_space_after_semicolon_in_for_statement = true
+csharp_space_before_semicolon_in_for_statement = false
+csharp_space_around_declaration_statements = false
+csharp_space_before_open_square_brackets = false
+csharp_space_between_empty_square_brackets = false
+csharp_space_between_square_brackets = false
+
+### Wrap options
+csharp_preserve_single_line_statements = false
+csharp_preserve_single_line_blocks = true
+
+### Using directive options
+csharp_using_directive_placement = outside_namespace : error
+dotnet_diagnostic.IDE0065.severity = error
+
+# Code Style Rules
+
+## .NET Code Style
+
+dotnet_style_qualification_for_event = false : error
+dotnet_style_qualification_for_field = false : error
+dotnet_style_qualification_for_method = false : error
+dotnet_style_qualification_for_property = false : error
+dotnet_diagnostic.IDE0003.severity = error
+dotnet_diagnostic.IDE0009.severity = error
+
+dotnet_style_predefined_type_for_locals_parameters_members = true : error
+dotnet_style_predefined_type_for_member_access = true : error
+dotnet_diagnostic.IDE0049.severity = error
+
+dotnet_style_require_accessibility_modifiers = always : error
+dotnet_diagnostic.IDE0040.severity = error
+
+dotnet_style_readonly_field = true : error
+dotnet_diagnostic.IDE0044.severity = error
+
+dotnet_style_parentheses_in_arithmetic_binary_operators = always_for_clarity : warning
+dotnet_style_parentheses_in_relational_binary_operators = always_for_clarity : warning
+dotnet_style_parentheses_in_other_binary_operators = always_for_clarity : warning
+dotnet_style_parentheses_in_other_operators = always_for_clarity : warning
+dotnet_diagnostic.IDE0047.severity = warning
+dotnet_diagnostic.IDE0048.severity = warning
+
+dotnet_style_object_initializer = true : error
+dotnet_diagnostic.IDE0017.severity = error
+
+dotnet_style_explicit_tuple_names = true : error
+dotnet_diagnostic.IDE0033.severity = error
+
+csharp_prefer_simple_default_expression = true : error
+dotnet_diagnostic.IDE0034.severity = error
+
+dotnet_style_prefer_inferred_tuple_names = true : error
+dotnet_style_prefer_inferred_anonymous_type_member_names = true : error
+dotnet_diagnostic.IDE0037.severity = error
+
+dotnet_style_prefer_conditional_expression_over_assignment = true : error
+dotnet_diagnostic.IDE0045.severity = error
+
+dotnet_style_prefer_conditional_expression_over_return = true : silent
+dotnet_diagnostic.IDE0046.severity = refactoring
+
+dotnet_style_prefer_compound_assignment = true : error
+dotnet_diagnostic.IDE0054.severity = error
+dotnet_diagnostic.IDE0074.severity = error
+
+dotnet_style_prefer_simplified_boolean_expressions = true : warning
+dotnet_diagnostic.IDE0075.severity = warning
+
+dotnet_style_coalesce_expression = true : error
+dotnet_diagnostic.IDE0029.severity = error
+dotnet_diagnostic.IDE0030.severity = error
+
+dotnet_style_null_propagation = true : error
+dotnet_diagnostic.IDE0031.severity = error
+
+dotnet_style_prefer_is_null_check_over_reference_equality_method = true : error
+dotnet_diagnostic.IDE0041.severity = error
+
+dotnet_style_collection_initializer = true : error
+dotnet_diagnostic.IDE0028.severity = error
+
+dotnet_style_prefer_auto_properties = true : warning
+dotnet_diagnostic.IDE0032.severity = warning
+
+dotnet_code_quality_unused_parameters = all : error
+dotnet_diagnostic.IDE0060.severity = error
+
+dotnet_remove_unnecessary_suppression_exclusions = none : warning
+dotnet_diagnostic.IDE0079.severity = warning
+
+dotnet_style_prefer_simplified_interpolation = true : error
+dotnet_diagnostic.IDE0071.severity = error
+
+## Rules without Style Options
+
+# IDE0010: Add missing cases
+dotnet_diagnostic.IDE0010.severity = error
+
+# IDE0001: Simplify name
+dotnet_diagnostic.IDE0001.severity = error
+
+# IDE0002: Simplify member access
+dotnet_diagnostic.IDE0002.severity = error
+
+# IDE0004: Remove unnecessary cast
+dotnet_diagnostic.IDE0004.severity = error
+
+# IDE0005: Using directive is unnecessary.
+dotnet_diagnostic.IDE0005.severity = error
+
+# IDE0100: Remove redundant equality
+dotnet_diagnostic.IDE0100.severity = error
+
+# IDE0035: Remove unreachable code
+dotnet_diagnostic.IDE0035.severity = warning
+
+# IDE0051: Remove unused private member
+dotnet_diagnostic.IDE0051.severity = warning
+
+# IDE0052: Remove unread private member
+dotnet_diagnostic.IDE0052.severity = warning
+
+# IDE0058: Remove unnecessary expression value
+dotnet_diagnostic.IDE0058.severity = refactoring
+
+# IDE0059: Remove unnecessary value assignment
+dotnet_diagnostic.IDE0059.severity = warning
+
+# IDE0070: Use 'System.HashCode.Combine'
+dotnet_diagnostic.IDE0070.severity = error
+
+## C# Code style
+
+csharp_style_pattern_local_over_anonymous_function = true : suggestion
+dotnet_diagnostic.IDE0039.severity = refactoring
+
+csharp_style_deconstructed_variable_declaration = true : warning
+dotnet_diagnostic.IDE0042.severity = warning
+
+csharp_style_implicit_object_creation_when_type_is_apparent = true
+dotnet_diagnostic.IDE0090.severity = error
+
+csharp_style_conditional_delegate_call = true : error
+dotnet_diagnostic.IDE1005.severity = error
+
+csharp_style_throw_expression = true : error
+dotnet_diagnostic.IDE0016.severity = error
+
+csharp_preferred_modifier_order = public, private, protected, internal, static, extern, new, virtual, abstract, sealed, override, readonly, unsafe, volatile, async : warning
+dotnet_diagnostic.IDE0036.severity = warning
+
+csharp_prefer_static_local_function = true
+dotnet_diagnostic.IDE0062.severity = warning
+
+csharp_style_inlined_variable_declaration = true : error
+dotnet_diagnostic.IDE0018.severity = error
+
+csharp_style_var_elsewhere = true : error
+csharp_style_var_for_built_in_types = false : error
+csharp_style_var_when_type_is_apparent = true : error
+dotnet_diagnostic.IDE0007.severity = error
+dotnet_diagnostic.IDE0008.severity = error
+
+csharp_style_expression_bodied_constructors = true : error
+dotnet_diagnostic.IDE0021.severity = error
+
+csharp_style_expression_bodied_methods = true : error
+dotnet_diagnostic.IDE0022.severity = error
+
+csharp_style_expression_bodied_operators = true : error
+dotnet_diagnostic.IDE0023.severity = error
+dotnet_diagnostic.IDE0024.severity = error
+
+csharp_style_expression_bodied_properties = true : error
+dotnet_diagnostic.IDE0025.severity = error
+
+csharp_style_expression_bodied_indexers = true : error
+dotnet_diagnostic.IDE0026.severity = error
+
+csharp_style_expression_bodied_accessors = true : error
+dotnet_diagnostic.IDE0027.severity = error
+
+csharp_style_expression_bodied_lambdas = true : error
+dotnet_diagnostic.IDE0053.severity = error
+
+csharp_style_expression_bodied_local_functions = true : error
+dotnet_diagnostic.IDE0061.severity = error
+
+csharp_style_pattern_matching_over_as_with_null_check = true : error
+dotnet_diagnostic.IDE0019.severity = error
+
+csharp_style_pattern_matching_over_is_with_cast_check = true : error
+dotnet_diagnostic.IDE0020.severity = error
+
+csharp_style_prefer_switch_expression = true : error
+dotnet_diagnostic.IDE0066.severity = error
+
+csharp_style_prefer_pattern_matching = true : error
+dotnet_diagnostic.IDE0078.severity = error
+
+csharp_style_prefer_not_pattern = true : error
+dotnet_diagnostic.IDE0083.severity = error
+
+csharp_prefer_braces = true : error
+dotnet_diagnostic.IDE0011.severity = error
+
+csharp_prefer_simple_using_statement = true : error
+dotnet_diagnostic.IDE0063.severity = error
+
+csharp_style_prefer_index_operator = true : warning
+dotnet_diagnostic.IDE0056.severity = warning
+
+csharp_style_prefer_range_operator = true : warning
+dotnet_diagnostic.IDE0057.severity = warning
+
+csharp_style_namespace_declarations = file_scoped : error
+dotnet_diagnostic.IDE0161.severity = error
+
+csharp_style_prefer_null_check_over_type_check = true : warning
+dotnet_diagnostic.IDE0150.severity = error
+
+## Rules without Style Options
+
+# IDE0050: Convert anonymous type to tuple
+dotnet_diagnostic.IDE0050.severity = warning
+
+# IDE0064: Make readonly fields writable
+dotnet_diagnostic.IDE0064.severity = error
+
+# IDE0072: Add missing cases to switch expression
+dotnet_diagnostic.IDE0072.severity = error
+
+# IDE0082: Convert typeof to nameof
+dotnet_diagnostic.IDE0082.severity = error
+
+# IDE0080: Remove unnecessary suppression operator
+dotnet_diagnostic.IDE0080.severity = error
+
+# IDE0110: Remove unnecessary discard
+dotnet_diagnostic.IDE0110.severity = warning
+
+# IDE1006: Naming Styles
+dotnet_diagnostic.IDE1006.severity = error
+
+# Naming Conventions
+dotnet_naming_symbols.const_field_symbols.applicable_kinds = field
+dotnet_naming_symbols.const_field_symbols.required_modifiers = const
+dotnet_naming_symbols.const_field_symbols.applicable_accessibilities = *
+dotnet_naming_style.const_field_symbols.capitalization = pascal_case
+
+dotnet_naming_rule.const_fields_must_be_pascal_case.severity = error
+dotnet_naming_rule.const_fields_must_be_pascal_case.symbols = const_field_symbols
+dotnet_naming_rule.const_fields_must_be_pascal_case.style = const_field_symbols
+
+dotnet_naming_symbols.private_field_symbol.applicable_kinds = field
+dotnet_naming_symbols.private_field_symbol.applicable_accessibilities = private
+dotnet_naming_style.private_field_style.capitalization = camel_case
+dotnet_naming_rule.private_fields_are_camel_case.severity = warning
+dotnet_naming_rule.private_fields_are_camel_case.symbols = private_field_symbol
+dotnet_naming_rule.private_fields_are_camel_case.style = private_field_style
+
+dotnet_naming_symbols.non_private_field_symbol.applicable_kinds = field
+dotnet_naming_symbols.non_private_field_symbol.applicable_accessibilities = public,internal,friend,protected,protected_internal,protected_friend
+dotnet_naming_style.non_private_field_style.capitalization = pascal_case
+dotnet_naming_rule.non_private_fields_are_pascal_case.severity = warning
+dotnet_naming_rule.non_private_fields_are_pascal_case.symbols = non_private_field_symbol
+dotnet_naming_rule.non_private_fields_are_pascal_case.style = non_private_field_style
+
+dotnet_naming_symbols.parameter_symbol.applicable_kinds = parameter
+dotnet_naming_style.parameter_style.capitalization = camel_case
+dotnet_naming_rule.parameters_are_camel_case.severity = warning
+dotnet_naming_rule.parameters_are_camel_case.symbols = parameter_symbol
+dotnet_naming_rule.parameters_are_camel_case.style = parameter_style
+
+dotnet_naming_symbols.non_interface_type_symbol.applicable_kinds = class,struct,enum,delegate
+dotnet_naming_style.non_interface_type_style.capitalization = pascal_case
+dotnet_naming_rule.non_interface_types_are_pascal_case.severity = error
+dotnet_naming_rule.non_interface_types_are_pascal_case.symbols = non_interface_type_symbol
+dotnet_naming_rule.non_interface_types_are_pascal_case.style = non_interface_type_style
+
+dotnet_naming_symbols.interface_type_symbol.applicable_kinds = interface
+dotnet_naming_style.interface_type_style.capitalization = pascal_case
+dotnet_naming_style.interface_type_style.required_prefix = I
+dotnet_naming_rule.interface_types_must_be_prefixed_with_I.severity = error
+dotnet_naming_rule.interface_types_must_be_prefixed_with_I.symbols = interface_type_symbol
+dotnet_naming_rule.interface_types_must_be_prefixed_with_I.style = interface_type_style
+
+dotnet_naming_symbols.member_symbol.applicable_kinds = method,property,event
+dotnet_naming_style.member_style.capitalization = pascal_case
+dotnet_naming_rule.members_are_pascal_case.severity = error
+dotnet_naming_rule.members_are_pascal_case.symbols = member_symbol
+dotnet_naming_rule.members_are_pascal_case.style = member_style
\ No newline at end of file
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 515e235b..380e5400 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -33,8 +33,8 @@ jobs:
steps:
- uses: actions/checkout@v4
- - name: Run dotnet format
- run: dotnet format --exclude ./examples/** --verify-no-changes
+ # - name: Run dotnet format
+ # run: dotnet format --exclude ./examples/** --verify-no-changes
build_and_test:
name: Build and Test
@@ -74,4 +74,4 @@ jobs:
dotnet test `
--configuration Release `
--no-build `
- --no-restore
\ No newline at end of file
+ --no-restore
diff --git a/.markdownlint.json b/.markdownlint.json
new file mode 100644
index 00000000..4b0a92f9
--- /dev/null
+++ b/.markdownlint.json
@@ -0,0 +1,5 @@
+{
+ "MD013": false,
+ "MD024": false,
+ "no-inline-html": false
+}
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
new file mode 100644
index 00000000..c5034bf8
--- /dev/null
+++ b/.vscode/extensions.json
@@ -0,0 +1,11 @@
+{
+ "recommendations": [
+ "ms-dotnettools.csdevkit",
+ "esbenp.prettier-vscode",
+ "davidanson.vscode-markdownlint",
+ "editorconfig.editorconfig",
+ "adrianwilczynski.user-secrets",
+ "dotjoshjohnson.xml",
+ "tintoy.msbuild-project-tools"
+ ]
+}
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 00000000..82edea02
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,62 @@
+{
+ "files.exclude": {
+ "**/.git": true,
+ "**/.svn": true,
+ "**/.hg": true,
+ "**/CVS": true,
+ "**/.DS_Store": true,
+ "**/Thumbs.db": true,
+ "**/node_modules": true,
+ "**/obj": true,
+ "**/bin": true,
+ "**/*.csproj.user": true
+ },
+
+ "search.exclude": {
+ "**/*.code-search": true,
+ "**/CIRepository/**": true
+ },
+
+ "editor.formatOnSave": true,
+ "editor.defaultFormatter": "esbenp.prettier-vscode",
+ "editor.codeActionsOnSave": {
+ "source.fixAll.eslint": "explicit"
+ },
+
+ "[xml]": {
+ "editor.defaultFormatter": "DotJoshJohnson.xml"
+ },
+
+ "[json]": {
+ "editor.quickSuggestions": {
+ "strings": true
+ },
+ "editor.suggest.insertMode": "replace",
+ "editor.defaultFormatter": "esbenp.prettier-vscode"
+ },
+
+ "[razor]": {
+ "editor.defaultFormatter": "ms-dotnettools.csharp"
+ },
+ "[aspnetcorerazor]": {
+ "editor.defaultFormatter": "ms-dotnettools.csharp"
+ },
+ "emmet.includeLanguages": {
+ "razor": "html"
+ },
+
+ "[csharp]": {
+ "editor.defaultFormatter": "ms-dotnettools.csharp"
+ },
+
+ "dotnet.defaultSolution": "Migration.Toolkit.sln",
+
+ "typescript.validate.enable": false,
+ "eslint.workingDirectories": [],
+
+ "[powershell]": {
+ "editor.defaultFormatter": "ms-vscode.powershell"
+ },
+
+ "terminal.integrated.defaultProfile.osx": "pwsh"
+}
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
deleted file mode 100644
index d59dc7ab..00000000
--- a/CODE_OF_CONDUCT.md
+++ /dev/null
@@ -1,46 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
-
-## Our Standards
-
-Examples of behavior that contributes to creating a positive environment include:
-
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
-
-Examples of unacceptable behavior by participants include:
-
-* The use of sexualized language or imagery and unwelcome sexual attention or advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a professional setting
-
-## Our Responsibilities
-
-Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
-
-Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
-
-## Scope
-
-This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at devrel@kentico.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
-
-Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [https://contributor-covenant.org/version/1/4][version]
-
-[homepage]: https://contributor-covenant.org
-[version]: https://contributor-covenant.org/version/1/4/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
deleted file mode 100644
index 01d1695c..00000000
--- a/CONTRIBUTING.md
+++ /dev/null
@@ -1,70 +0,0 @@
-# Ways to contribute
-
-
-There are many different ways in which you can contribute. One of the easiest ways is simply to use our software and provide us with your feedback through the right channel. You can also help us improve the open-source projects by submitting pull requests with code and documentation changes.
-
-## Where to get support
-Please note that **level of provided support is always determined by the [LICENSE](LICENSE.md)** of a given open-source project. Also, always make sure you use the **[latest version](../../releases)** of any given OS project. We can't provide any help for older versions. We don't want to make things complicated so we try to take the same approach in all our repositories.
-
-### I found a bug in a Kentico's open-source project
-
-
-Sorry to hear that. Just log a new [GitHub issue](../../issues) and someone will take a look at it. Remember, the more information you provide, the easier it will be to fix the issue. If you feel like it, you can also fix the bug on your own and submit a new pull request.
-
-### I need help with using the projects and/or coding
-
-
-To get help with coding and structuring your projects, use [StackOverflow](https://stackoverflow.com/) to ask questions with one of the following tags:
-- [`kentico-kontent`](https://stackoverflow.com/questions/tagged/kentico-kontent)
-- [`kentico`](https://stackoverflow.com/questions/tagged/kentico)
-
-Our team members and the community monitor these channels on a regular basis.
-
-### I want to report a security bug
-
-
-Security issues and bugs should be reported privately, via email, to the Kentico Developer Relations Team devrel@kentico.com. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message.
-
-
-### I have an idea for a new feature (or feedback on existing functionality)
-
-
-Everybody loves new features! You can submit a new [feature request](../../issues) or you can code it on your own and [send us a pull request](#submitting-pull-requests). In either case, don't forget to mention what's the use case and what's the expected output.
-
-
-## Submitting pull requests
-
-
-Unless you're fixing a typo, it's usually a good idea to discuss the feature before you submit a pull request with code changes, so let's start with submitting a new [GitHub issue](../../issues) and discussing the whether it fits the vision of a given project.
-You might also read these two blogs posts on contributing code: [Open Source Contribution Etiquette](http://tirania.org/blog/archive/2010/Dec-31.html) by Miguel de Icaza and [Don't "Push" Your Pull Requests](https://www.igvita.com/2011/12/19/dont-push-your-pull-requests/) by Ilya Grigorik. Note that all code submissions will be rigorously reviewed and tested by the Kentico Maintainers teams, and only those that meet an high bar for both quality and design/roadmap appropriateness will be merged into the source.
-
-
-### Example - process of contribution
-If not stated otherwise, we use [feature branch workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow).
-
-To start with coding, fork the repository you want to contribute to, create a new branch, and start coding. Once the functionality is [done](#Definition-of-Done), you can submit a [pull request](https://help.github.com/articles/about-pull-requests/).
-
-### Definition of Done
-
-
-- New/fixed code is covered with tests
-- CI can build the code
-- All tests are pass
-- New version number follows [semantic versioning](https://semver.org/)
-- Coding style (spaces, indentation) is in line with the rest of the code in a given repository
-- Documentation is updated (e.g. code examples in README, Wiki pages, etc.)
-- All `public` members are documented (using XML doc, phpdoc, etc.)
-- Code doesn't contain any secrets (private keys, etc.)
-- Commit messages are clear. Please read these articles: [Writing good commit messages](https://github.com/erlang/otp/wiki/Writing-good-commit-messages), [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), [On commit messages](https://who-t.blogspot.com/2009/12/on-commit-messages.html)
-
-
-### Feedback
-
-
-Your pull request will now go through extensive checks by the subject matter experts on our team. Please be patient. Update your pull request according to feedback until it is approved by one of the Kentico maintainers. After that, one of our team members may adjust the branch you merge into based on the expected release schedule.
-
-
-## Code of Conduct
-
-
-The Kentico team is committed to fostering a welcoming community, therefore this project has adopted the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). If you have any additional questions or comments, you can contact us directly at devrel@kentico.com.
diff --git a/Directory.Build.props b/Directory.Build.props
index 5dda3a27..233958ca 100644
--- a/Directory.Build.props
+++ b/Directory.Build.props
@@ -2,7 +2,6 @@
net8.0
enable
-
enable
diff --git a/README.md b/README.md
index 1709a844..2af70dc6 100644
--- a/README.md
+++ b/README.md
@@ -1,151 +1,27 @@
-[//]: # "[![Contributors][contributors-shield]][contributors-url]"
-[//]: # "[![Forks][forks-shield]][forks-url]"
-[//]: # "[![Stargazers][stars-shield]][stars-url]"
-[//]: # "[![Issues][issues-shield]][issues-url]"
-[//]: # "[![MIT License][license-shield]][license-url]"
-[//]: # "[![Discord][discussion-shield]][discussion-url]"
-
-
# Xperience by Kentico: Kentico Migration Tool
+[](https://github.com/Kentico/.github/blob/main/SUPPORT.md#full-support)
+
[](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/actions/workflows/build.yml)
## Description
+This repository is part of the [Xperience by Kentico Migration Toolkit](https://github.com/Kentico/xperience-by-kentico-migration-toolkit).
+
The Kentico Migration Tool transfers content and other data from **Kentico Xperience 13**, **Kentico 12** or **Kentico 11** to **Xperience by Kentico**.
-## Prerequisites & Compatibility
-
-### Source
-
-The migration currently supports the Kentico Xperience 13, Kentico 12 or Kentico 11 as the source instance. See the following sections for compatibility information and limitations of respective versions.
-
-#### Kentico Xperience 13
-
-* The source of the migration data must be a Kentico Xperience 13 instance, with **Refresh 5** ([hotfix](https://devnet.kentico.com/download/hotfixes) 13.0.64) or newer applied.
-* The development model (Core or MVC 5) does not affect the migration - both are supported.
-* The source instance's database and file system must be accessible from the environment where you run the Kentico Migration Tool.
-* All features described in this repository are available for migration from Kentico Xperience 13.
-
-#### Kentico 12
-
-* The source of the migration data can be any hotfix version of the Kentico 12.
-* Only MVC development model is supported by this tool. Any Portal Engine project that you wish to migrate to Xperience by Kentico needs to be [migrated to MVC](https://www.youtube.com/watch?v=g2oeHU0h1e0) first.
-* The source instance's database and file system must be accessible from the environment where you run the this tool.
-* Migration of Page Builder content is not supported. Only structured data of pages is migrated.
- * As a result, [source instance API discovery](/Migration.Toolkit.CLI/README.md#source-instance-api-discovery) is also not available.
-* This repository describes the migration of Kentico Xperience 13 feature set. Only features relevant to Kentico 12 are migrated for this version.
-
-#### Kentico 11
-
-* The source of the migration data can be any hotfix version of the Kentico 11. If you encounter any issues, it is recommended to update to the latest hotfix.
-* Only MVC development model is supported by this tool. Any Portal Engine project that you wish to migrate to Xperience by Kentico needs to be [migrated to MVC](https://www.youtube.com/watch?v=g2oeHU0h1e0) first.
-* The source instance's database and file system must be accessible from the environment where you run this tool.
-* Only structured data of pages is migrated as Page Builder is not present in Kentico 11.
- * As a result, [source instance API discovery](/Migration.Toolkit.CLI/README.md#source-instance-api-discovery) is also not available.
-* This repository describes the migration of Kentico Xperience 13 feature set. Only features relevant to Kentico 11 are migrated for this version.
-
-### Target
-
-* The Kentico Migration Tool is periodically updated to support migration to the **latest version** of Xperience by Kentico. However, there may be delays between Xperience by Kentico releases and tool updates.
- * Currently, Xperience by Kentico **29.1.0** is tested and supported.
-* The target instance's database and file system must be accessible from the environment where you run this tool.
-* The target instance's database must be empty except for data from the source instance created by previous runs of this tool to avoid conflicts and inconsistencies.
-
-## Supported data and limitations
-
-The Kentico Migration Tool does not transfer all data available in the source instance. Xperience by Kentico currently provides a smaller, more focused set of features. As a result, some objects are discarded or migrated to a suitable alternative.
-
-This tool only supports content and objects **stored in the database** and related binary data on the file system, such as media library files. Code, customizations, and any other types of content need to be migrated manually to the target project and adjusted for Xperience by Kentico.
-
-Currently, the Kentico Migration Tool supports the following types of data:
-
-* **Sites**
- * The tool migrates each site on the source to a [website channel](https://docs.kentico.com/x/34HFC) object in Xperience by Kentico.
-* **Cultures**
- * The set of cultures used across all sites in the source gets mapped to a [language](https://docs.kentico.com/x/OxT_Cw) in the _Languages_ application.
-* **Content types** (_Page types_ in earlier Kentico versions)
- * The Kentico Migration Tool attempts to map the _Data type_ and _Form control_ of page type fields to an appropriate equivalent in Xperience by Kentico. This mapping is not always possible and does not work for custom data types or form controls. We recommend checking your content type fields after the migration and adjusting them if necessary.
- * The migration includes only page types assigned to at least one site on the source instance.
- * Xperience by Kentico currently does not support:
- * Macro expressions in page type field default values or other settings. Content type fields containing macros will not work correctly after the migration.
- * Categories for page type fields. Field categories are not migrated with page types.
- * Page type inheritance. Page types that inherit fields are migrated including all inherited fields but the binding to the parent page type is not preserved.
- * However, you can create [reusable field schemas](./Migration.Toolkit.CLI/README.md#convert-page-types-to-reusable-field-schemas) for page types from which other page types inherit.
- * All migrated Content types have the **Include in routing** option enabled (the migration never creates pages without URL and routing).
-* **Pages**
- * The migration includes the following versions of pages:
- * _Published_
- * _Latest draft version_ - for published pages, the version is migrated to the _Draft_ [workflow step](https://docs.kentico.com/x/JwKQC); for pages that do not have a published version, the version is migrated to the _Draft (initial)_ workflow step.
- * _Archived_
- * Each page gets assigned under its corresponding website channel.
- * Linked pages are currently not supported in Xperience by Kentico. The migration creates standard page copies for any linked pages on the source instance.
- * Page permissions (ACLs) are currently not supported in Xperience by Kentico and are not migrated.
- * Migration of Page Builder content is only available for Kentico Xperience 13.
-* **Page attachments**
- * Page attachments are not supported in Xperience by Kentico. Attachments are migrated into media libraries. See [`Migration.Toolkit.CLI/README.md - Attachments`](./Migration.Toolkit.CLI/README.md#Attachments) for detailed information about the conversion process.
-* **Preset page templates** (_Custom page templates_ in Kentico Xperience 13)
- * Migration of custom page templates is only available for Kentico Xperience 13.
-* **Categories**
- * Xperience by Kentico uses a different approach to categorization. Categories are migrated to [taxonomies](https://docs.kentico.com/x/taxonomies_xp) and selected categories for each page are assigned to pages in the target instance via a [reusable field schema](https://docs.kentico.com/x/D4_OD). See [`Migration.Toolkit.CLI/README.md - Categories`](./Migration.Toolkit.CLI/README.md#categories).
- * [Categories stored as a field of pages](https://docs.kentico.com/x/wA_RBg) and [personal categories](https://docs.kentico.com/x/IgqRBg) are not supported.
-* **Media libraries and media files**
- * Media library permissions are currently not supported in Xperience by Kentico and are not migrated.
-* **Forms**
- * The migration does not include the content of form autoresponder and notification emails. You can migrate form autoresponders to Xperience by Kentico manually by copying your HTML code and content into Email templates and Emails. See [Emails](https://docs.kentico.com/x/IaDWCQ).
-* **Users**
- * Xperience by Kentico uses separate entities for users with access to the administration interface (_CMS\_User_ table) and live site visitor accounts (_CMS\_Member_ table). Consequently, only users whose _Privilege level_ is _Editor_ or higher are migrated (_Users_ -> edit a user -> _General_ tab).
- * Users in Xperience by Kentico must have an email address. Migration is only supported for users who have a unique email address value on the source instance.
- * Custom user fields are an optional part of _module class_ migration.
- * Live site users are represented using a separate **Member** entity and stored in the _CMS_Member_ table. The migration identifies live site users as those without access to the administration interface - accounts with _Privilege level_ set to _None_ (Users -> edit a user -> General tab).
-* **Roles**
- * Only roles that have at least one user whose _Privilege level_ is set to _Editor_ and above are migrated.
- * Because Xperience by Kentico uses a different [permission model](https://docs.kentico.com/x/7IVwCg), no existing role permissions or UI personalization settings are migrated. After the migration, the permissions for each role must be configured again.
-* **Contacts**
- * The target instance's _OMContact_ and _OMActivity_ database tables must be empty for performance reasons.
- * Custom contact fields are an optional part of _module class_ migration.
-* **Activities**
-* **Consents and consent agreements**
-* **Modules and classes**
- * The migration includes the following:
- * Custom modules
- * All classes associated with custom modules
- * All data stored within custom module classes
- * The following customizable system classes and their custom fields: _User_, _Media file_, _Contact management - Account_ (however, accounts are currently not supported in Xperience by Kentico), _Contact management - Contact_
- * Module and class migration does NOT include:
- * UI elements and all related user interface settings. The administration of Xperience by Kentico uses a different technology stack than earlier Kentico versions and is incompatible. To learn how to build the administration UI, see [Extend the administration interface](https://docs.kentico.com/x/GwKQC) and [Example - Offices management application](https://docs.kentico.com/x/hIFwCg).
- * Alternative forms under classes and UI-related configuration of class fields (field labels, Form controls, etc.). After the migration, you must manually create the appropriate [UI forms](https://docs.kentico.com/x/V6rWCQ) in Xperience by Kentico.
- * Custom settings under modules, which are currently not supported in Xperience by Kentico
- * Module permissions (permissions work differently in Xperience by Kentico - see [Role management](https://docs.kentico.com/x/7IVwCg) and [UI page permission checks](https://docs.kentico.com/x/8IKyCg))
- * As with all object types, the Kentico Migration Tool does not transfer code files to the target project. You must manually move all code files generated for your custom classes (_Info_, _InfoProvider_, etc.).
-* **Custom tables**
- * Custom tables are not supported in Xperience by Kentico. Data from custom tables is migrated to the target instance as custom modules.
- * The migration only transfers data from custom tables to the custom module (_CMS\_Resource_) database table.
- * Any user interface, listings, filters, and other functionality related to migrated custom tables needs to be implemented in the target instance.
-* **Setting values**
- * The migration only transfers the settings that exist in Xperience by Kentico.
- * The migration excludes site-specific settings that do not have a corresponding website channel-specific alternative in Xperience by Kentico.
-
-* **Countries and states**
-
-### Unsupported data
-
-The following types of data exist in Xperience by Kentico but are currently **not supported** by the Kentico Migration Tool:
-
-* **Contact groups**
- * Static contact groups are currently not supported in Xperience by Kentico.
- * The condition format for dynamic contact groups is not compatible. To migrate contact groups:
- 1. Migrate your contacts using the tool.
- 2. Create the [contact groups](https://docs.kentico.com/x/o4PWCQ) manually in Xperience by Kentico.
- 3. Build equivalent conditions.
- 4. Recalculate the contact groups.
-* **License keys**
- * Xperience by Kentico uses a different license key format.
-
- Additionally, object values or other content with **Macros** will not work correctly after the migration. Macro expressions are currently not supported for most data in Xperience by Kentico.
-
-
-## Get started
+## Library Version Matrix
+
+| Xperience Version | Library Version |
+| ----------------- | --------------- |
+| >= 29.1.0 | >= 1.0.0 |
+
+## Dependencies
+
+- [ASP.NET Core 8.0](https://dotnet.microsoft.com/en-us/download)
+- [Xperience by Kentico](https://docs.kentico.com/changelog)
+
+## Quick Start
Follow the steps below to run the Kentico Migration Tool:
@@ -156,45 +32,52 @@ Follow the steps below to run the Kentico Migration Tool:
5. Open the command line prompt.
6. Navigate to the output directory of the `Migration.Toolkit.CLI` project.
7. Run the `Migration.Toolkit.CLI.exe migrate` command.
- * The following example shows the command with all parameters for complete migration:
- ```powershell
- Migration.Toolkit.CLI.exe migrate --sites --custom-modules --users --settings-keys --page-types --pages --attachments --contact-management --forms --media-libraries --data-protection --countries
- ```
+ - The following example shows the command with all parameters for complete migration:
+
+ ```powershell
+ Migration.Toolkit.CLI.exe migrate --sites --custom-modules --users --settings-keys --page-types --pages --attachments --contact-management --forms --media-libraries --data-protection --countries
+ ```
8. Observe the command line output. The command output is also stored in a log file (`logs\log-.txt` under the output directory by default), which you can review later.
9. Review the migration protocol, which provides information about the result of the migration, lists required manual steps, etc.
- * You can find the protocol in the location specified by the `MigrationProtocolPath` key in the `appsettings.json` configuration file.
- * For more information, see [`Migration.Toolkit.CLI/MIGRATION_PROTOCOL_REFERENCE.md`](./Migration.Toolkit.CLI/MIGRATION_PROTOCOL_REFERENCE.md).
+ - You can find the protocol in the location specified by the `MigrationProtocolPath` key in the `appsettings.json` configuration file.
+ - For more information, see [`Migration.Toolkit.CLI/MIGRATION_PROTOCOL_REFERENCE.md`](./Migration.Toolkit.CLI/MIGRATION_PROTOCOL_REFERENCE.md).
The data is now migrated to the target Xperience by Kentico instance according to your configuration. See [`Migration.Toolkit.CLI/README.md`](./Migration.Toolkit.CLI/README.md) for detailed information about the migration CLI, configuration options, instructions related to individual object types, and manual migration steps.
+## Full Instructions
+
+View the [Usage Guide](./docs/Usage-Guide.md) for more detailed instructions.
+
## Changelog of recent updates
-* **June 13, 2024**
- * Migration of categories to taxonomies is available
-* **March 11, 2024**
- * Kentico Xperience 11 instances are supported as a source of migration
-* **February 1, 2024**
- * Kentico Xperience 12 instances are supported as a source of migration
+- **June 13, 2024**
+ - Migration of categories to taxonomies is available
+- **March 11, 2024**
+ - Kentico Xperience 11 instances are supported as a source of migration
+- **February 1, 2024**
+ - Kentico Xperience 12 instances are supported as a source of migration
-
## Contributing
-See [`CONTRIBUTING.md`](./CONTRIBUTING.md) to learn how to file issues, start discussions, and submit contributions.
+To see the guidelines for Contributing to Kentico open source software, please see [Kentico's `CONTRIBUTING.md`](https://github.com/Kentico/.github/blob/main/CONTRIBUTING.md) for more information and follow the [Kentico's `CODE_OF_CONDUCT`](https://github.com/Kentico/.github/blob/main/CODE_OF_CONDUCT.md).
-Please provide all available information about the problem or error when submitting issues. If possible, include the command line output log file and migration protocol generated by the `Migration.Toolkit.CLI.exe migrate` command.
+Instructions and technical details for contributing to **this** project can be found in [Contributing Setup](./docs/Contributing-Setup.md).
-
## License
Distributed under the MIT License. See [`LICENSE.md`](./LICENSE.md) for more information.
## Support
-This contribution has **Full support by 7-day bug-fix policy**.
+[](https://github.com/Kentico/.github/blob/main/SUPPORT.md#full-support)
+
+This project has **Full support by 7-day bug-fix policy**.
See [`SUPPORT.md`](https://github.com/Kentico/.github/blob/main/SUPPORT.md#full-support) for more information.
-For any security issues see [`SECURITY.md`](https://github.com/Kentico/.github/blob/main/SECURITY.md).
\ No newline at end of file
+## Security
+
+For any security issues see [Kentico's `SECURITY.md`](https://github.com/Kentico/.github/blob/main/SECURITY.md).
diff --git a/docs/Contributing-Setup.md b/docs/Contributing-Setup.md
new file mode 100644
index 00000000..bf0c4549
--- /dev/null
+++ b/docs/Contributing-Setup.md
@@ -0,0 +1,3 @@
+# Contributing Setup
+
+Please provide all available information about the problem or error when submitting issues. If possible, include the command line output log file and migration protocol generated by the `Migration.Toolkit.CLI.exe migrate` command.
diff --git a/docs/Supported-Data.md b/docs/Supported-Data.md
new file mode 100644
index 00000000..1e6c9895
--- /dev/null
+++ b/docs/Supported-Data.md
@@ -0,0 +1,92 @@
+# Supported Data
+
+The Kentico Migration Tool does not transfer all data available in the source instance. Xperience by Kentico currently provides a smaller, more focused set of features. As a result, some objects are discarded or migrated to a suitable alternative.
+
+This tool only supports content and objects **stored in the database** and related binary data on the file system, such as media library files. Code, customizations, and any other types of content need to be migrated manually to the target project and adjusted for Xperience by Kentico.
+
+Currently, the Kentico Migration Tool supports the following types of data:
+
+- **Sites**
+ - The tool migrates each site on the source to a [website channel](https://docs.kentico.com/x/34HFC) object in Xperience by Kentico.
+- **Cultures**
+ - The set of cultures used across all sites in the source gets mapped to a [language](https://docs.kentico.com/x/OxT_Cw) in the _Languages_ application.
+- **Content types** (_Page types_ in earlier Kentico versions)
+ - The Kentico Migration Tool attempts to map the _Data type_ and _Form control_ of page type fields to an appropriate equivalent in Xperience by Kentico. This mapping is not always possible and does not work for custom data types or form controls. We recommend checking your content type fields after the migration and adjusting them if necessary.
+ - The migration includes only page types assigned to at least one site on the source instance.
+ - Xperience by Kentico currently does not support:
+ - Macro expressions in page type field default values or other settings. Content type fields containing macros will not work correctly after the migration.
+ - Categories for page type fields. Field categories are not migrated with page types.
+ - Page type inheritance. Page types that inherit fields are migrated including all inherited fields but the binding to the parent page type is not preserved.
+ - However, you can create [reusable field schemas](./Migration.Toolkit.CLI/README.md#convert-page-types-to-reusable-field-schemas) for page types from which other page types inherit.
+ - All migrated Content types have the **Include in routing** option enabled (the migration never creates pages without URL and routing).
+- **Pages**
+ - The migration includes the following versions of pages:
+ - _Published_
+ - _Latest draft version_ - for published pages, the version is migrated to the _Draft_ [workflow step](https://docs.kentico.com/x/JwKQC); for pages that do not have a published version, the version is migrated to the _Draft (initial)_ workflow step.
+ - _Archived_
+ - Each page gets assigned under its corresponding website channel.
+ - Linked pages are currently not supported in Xperience by Kentico. The migration creates standard page copies for any linked pages on the source instance.
+ - Page permissions (ACLs) are currently not supported in Xperience by Kentico and are not migrated.
+ - Migration of Page Builder content is only available for Kentico Xperience 13.
+- **Page attachments**
+ - Page attachments are not supported in Xperience by Kentico. Attachments are migrated into media libraries. See [`Migration.Toolkit.CLI/README.md - Attachments`](./Migration.Toolkit.CLI/README.md#Attachments) for detailed information about the conversion process.
+- **Preset page templates** (_Custom page templates_ in Kentico Xperience 13)
+ - Migration of custom page templates is only available for Kentico Xperience 13.
+- **Categories**
+ - Xperience by Kentico uses a different approach to categorization. Categories are migrated to [taxonomies](https://docs.kentico.com/x/taxonomies_xp) and selected categories for each page are assigned to pages in the target instance via a [reusable field schema](https://docs.kentico.com/x/D4_OD). See [`Migration.Toolkit.CLI/README.md - Categories`](./Migration.Toolkit.CLI/README.md#categories).
+ - [Categories stored as a field of pages](https://docs.kentico.com/x/wA_RBg) and [personal categories](https://docs.kentico.com/x/IgqRBg) are not supported.
+- **Media libraries and media files**
+ - Media library permissions are currently not supported in Xperience by Kentico and are not migrated.
+- **Forms**
+ - The migration does not include the content of form autoresponder and notification emails. You can migrate form autoresponders to Xperience by Kentico manually by copying your HTML code and content into Email templates and Emails. See [Emails](https://docs.kentico.com/x/IaDWCQ).
+- **Users**
+ - Xperience by Kentico uses separate entities for users with access to the administration interface (_CMS_User_ table) and live site visitor accounts (_CMS_Member_ table). Consequently, only users whose _Privilege level_ is _Editor_ or higher are migrated (_Users_ -> edit a user -> _General_ tab).
+ - Users in Xperience by Kentico must have an email address. Migration is only supported for users who have a unique email address value on the source instance.
+ - Custom user fields are an optional part of _module class_ migration.
+ - Live site users are represented using a separate **Member** entity and stored in the _CMS_Member_ table. The migration identifies live site users as those without access to the administration interface - accounts with _Privilege level_ set to _None_ (Users -> edit a user -> General tab).
+- **Roles**
+ - Only roles that have at least one user whose _Privilege level_ is set to _Editor_ and above are migrated.
+ - Because Xperience by Kentico uses a different [permission model](https://docs.kentico.com/x/7IVwCg), no existing role permissions or UI personalization settings are migrated. After the migration, the permissions for each role must be configured again.
+- **Contacts**
+ - The target instance's _OMContact_ and _OMActivity_ database tables must be empty for performance reasons.
+ - Custom contact fields are an optional part of _module class_ migration.
+- **Activities**
+- **Consents and consent agreements**
+- **Modules and classes**
+ - The migration includes the following:
+ - Custom modules
+ - All classes associated with custom modules
+ - All data stored within custom module classes
+ - The following customizable system classes and their custom fields: _User_, _Media file_, _Contact management - Account_ (however, accounts are currently not supported in Xperience by Kentico), _Contact management - Contact_
+ - Module and class migration does NOT include:
+ - UI elements and all related user interface settings. The administration of Xperience by Kentico uses a different technology stack than earlier Kentico versions and is incompatible. To learn how to build the administration UI, see [Extend the administration interface](https://docs.kentico.com/x/GwKQC) and [Example - Offices management application](https://docs.kentico.com/x/hIFwCg).
+ - Alternative forms under classes and UI-related configuration of class fields (field labels, Form controls, etc.). After the migration, you must manually create the appropriate [UI forms](https://docs.kentico.com/x/V6rWCQ) in Xperience by Kentico.
+ - Custom settings under modules, which are currently not supported in Xperience by Kentico
+ - Module permissions (permissions work differently in Xperience by Kentico - see [Role management](https://docs.kentico.com/x/7IVwCg) and [UI page permission checks](https://docs.kentico.com/x/8IKyCg))
+ - As with all object types, the Kentico Migration Tool does not transfer code files to the target project. You must manually move all code files generated for your custom classes (_Info_, _InfoProvider_, etc.).
+- **Custom tables**
+ - Custom tables are not supported in Xperience by Kentico. Data from custom tables is migrated to the target instance as custom modules.
+ - The migration only transfers data from custom tables to the custom module (_CMS_Resource_) database table.
+ - Any user interface, listings, filters, and other functionality related to migrated custom tables needs to be implemented in the target instance.
+- **Setting values**
+
+ - The migration only transfers the settings that exist in Xperience by Kentico.
+ - The migration excludes site-specific settings that do not have a corresponding website channel-specific alternative in Xperience by Kentico.
+
+- **Countries and states**
+
+## Unsupported data
+
+The following types of data exist in Xperience by Kentico but are currently **not supported** by the Kentico Migration Tool:
+
+- **Contact groups**
+ - Static contact groups are currently not supported in Xperience by Kentico.
+ - The condition format for dynamic contact groups is not compatible. To migrate contact groups:
+ 1. Migrate your contacts using the tool.
+ 2. Create the [contact groups](https://docs.kentico.com/x/o4PWCQ) manually in Xperience by Kentico.
+ 3. Build equivalent conditions.
+ 4. Recalculate the contact groups.
+- **License keys**
+ - Xperience by Kentico uses a different license key format.
+
+Additionally, object values or other content with **Macros** will not work correctly after the migration. Macro expressions are currently not supported for most data in Xperience by Kentico.
diff --git a/docs/Usage-Guide.md b/docs/Usage-Guide.md
new file mode 100644
index 00000000..7b320352
--- /dev/null
+++ b/docs/Usage-Guide.md
@@ -0,0 +1,52 @@
+# Usage Guide
+
+Below you can find a list of prerequisites for the versions of Kentico supported by this migration tool.
+
+For a full list of content and data that is supported by the migration tool, please see [Supported Data](/docs/Supported-Data.md).
+
+## Source
+
+The migration currently supports the Kentico Xperience 13, Kentico 12 or Kentico 11 as the source instance. See the following sections for compatibility information and limitations of respective versions.
+
+### Kentico Xperience 13
+
+- The source of the migration data must be a Kentico Xperience 13 instance, with [Refresh 5](https://docs.kentico.com/13/release-notes-xperience-13#ReleasenotesXperience13-Ref5), [hotfix 13.0.64](https://devnet.kentico.com/download/hotfixes) or newer applied.
+- The development model (Core or MVC 5) does not affect the migration - both are supported.
+- The source instance's database and file system must be accessible from the environment where you run the Kentico Migration Tool.
+- All features described in this repository are available for migration from Kentico Xperience 13.
+
+[](/images/xperience-by-kentico-migration-toolkit-kentico-migration-tool-kentico-xperience-13-embedded.jpg)
+
+### Kentico 12 MVC
+
+- The source of the migration data can be any hotfix version of the Kentico 12.
+ - If you encounter any issues, it is recommended to update to the latest hotfix.
+- Only MVC development model is supported by this tool. Any Portal Engine project that you wish to migrate to Xperience by Kentico needs to be [migrated to MVC](https://www.youtube.com/watch?v=g2oeHU0h1e0) first.
+- The source instance's database and file system must be accessible from the environment where you run the this tool.
+- This repository describes the migration of the Kentico Xperience 13 feature set, however only features relevant to Kentico 12 MVC are migrated for this version.
+
+[](/images/xperience-by-kentico-migration-toolkit-kentico-migration-tool-kentico-12-mvc-embedded.jpg)
+
+### Kentico 11 and 12 Portal Engine
+
+- The source of the migration data can be any hotfix version of the Kentico 12 or Kentico 11.
+ - If you encounter any issues, it is recommended to update to the latest hotfix.
+- The source instance's database and file system must be accessible from the environment where you run the this tool.
+- Migration of Page Builder content is not supported. Only structured data of pages is migrated.
+ - As a result, [source instance API discovery](/Migration.Toolkit.CLI/README.md#source-instance-api-discovery) is also not available.
+- This repository describes the migration of the Kentico Xperience 13 feature set, however only features relevant to Kentico 11 and 12 Portal Engine are migrated for this version.
+
+[](/images/xperience-by-kentico-migration-toolkit-kentico-migration-tool-kentico-10-12-portal-engine-embedded.jpg)
+
+## Target
+
+- The Kentico Migration Tool is periodically updated to support migration to the **latest version** of Xperience by Kentico. However, there may be delays between Xperience by Kentico releases and tool updates.
+ - See the [README](/README.md#library-version-matrix) for supported releases of Xperience by Kentico.
+- The target instance's database and file system must be accessible from the environment where you run this tool.
+- The target instance's database must be empty except for data from the source instance created by previous runs of this tool to avoid conflicts and inconsistencies.
+
+## Upgrade paths
+
+The full set of upgrade paths to Xperience by Kentico can be seen below.
+
+[](/images/xperience-by-kentico-migration-toolkit-kentico-migration-tool-full-embedded.jpg)
diff --git a/images/xperience-by-kentico-migration-toolkit-kentico-migration-tool-full-embedded.jpg b/images/xperience-by-kentico-migration-toolkit-kentico-migration-tool-full-embedded.jpg
new file mode 100644
index 00000000..696be305
Binary files /dev/null and b/images/xperience-by-kentico-migration-toolkit-kentico-migration-tool-full-embedded.jpg differ
diff --git a/images/xperience-by-kentico-migration-toolkit-kentico-migration-tool-kentico-10-12-portal-engine-embedded.jpg b/images/xperience-by-kentico-migration-toolkit-kentico-migration-tool-kentico-10-12-portal-engine-embedded.jpg
new file mode 100644
index 00000000..17730cb8
Binary files /dev/null and b/images/xperience-by-kentico-migration-toolkit-kentico-migration-tool-kentico-10-12-portal-engine-embedded.jpg differ
diff --git a/images/xperience-by-kentico-migration-toolkit-kentico-migration-tool-kentico-12-mvc-embedded.jpg b/images/xperience-by-kentico-migration-toolkit-kentico-migration-tool-kentico-12-mvc-embedded.jpg
new file mode 100644
index 00000000..dff30fa4
Binary files /dev/null and b/images/xperience-by-kentico-migration-toolkit-kentico-migration-tool-kentico-12-mvc-embedded.jpg differ
diff --git a/images/xperience-by-kentico-migration-toolkit-kentico-migration-tool-kentico-xperience-13-embedded.jpg b/images/xperience-by-kentico-migration-toolkit-kentico-migration-tool-kentico-xperience-13-embedded.jpg
new file mode 100644
index 00000000..9de1ae80
Binary files /dev/null and b/images/xperience-by-kentico-migration-toolkit-kentico-migration-tool-kentico-xperience-13-embedded.jpg differ