Skip to content

Commit dcd469e

Browse files
feversocialfeversocial
committed
Added documentation about Migration SDK, necessary to make it public
1 parent ecc8d0e commit dcd469e

File tree

4 files changed

+169
-12
lines changed

4 files changed

+169
-12
lines changed

‎_data/sidebars/ca_devscu_sidebar.yml‎

Lines changed: 19 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -46,15 +46,22 @@ entries:
4646
- title: Troubleshooting
4747
url: /docs/ca/devscu/troubleshooting/troubleshooting-spryker-code-upgrader-issues.html
4848
nested:
49-
- title: Check Spryker Code Upgrader logs
50-
url: /docs/ca/devscu/check-spryker-code-upgrader-logs.html
51-
- title: "Entity does not exist: Pyz prefix"
52-
url: /docs/ca/devscu/troubleshooting/entity-does-not-exist–pyz-prefix.html
53-
- title: "TransportException: Cannot move pack"
54-
url: /docs/ca/devscu/troubleshooting/transportexception-cannot-move-pack.html
55-
- title: The process exceeded the timeout
56-
url: /docs/ca/devscu/troubleshooting/the-process-exceeded-the-timeout.html
57-
- title: You have an unprocessed PR from a previous update
58-
url: /docs/ca/devscu/troubleshooting/you-have-an-unprocessed-pr-from-a-previous-update.html
59-
- title: A PHP extension is missing from your system
60-
url: /docs/ca/devscu/troubleshooting/a-php-extension-is-missing-from-your-system.html
49+
- title: Check Spryker Code Upgrader logs
50+
url: /docs/ca/devscu/check-spryker-code-upgrader-logs.html
51+
- title: "Entity does not exist: Pyz prefix"
52+
url: /docs/ca/devscu/troubleshooting/entity-does-not-exist–pyz-prefix.html
53+
- title: "TransportException: Cannot move pack"
54+
url: /docs/ca/devscu/troubleshooting/transportexception-cannot-move-pack.html
55+
- title: The process exceeded the timeout
56+
url: /docs/ca/devscu/troubleshooting/the-process-exceeded-the-timeout.html
57+
- title: You have an unprocessed PR from a previous update
58+
url: /docs/ca/devscu/troubleshooting/you-have-an-unprocessed-pr-from-a-previous-update.html
59+
- title: A PHP extension is missing from your system
60+
url: /docs/ca/devscu/troubleshooting/a-php-extension-is-missing-from-your-system.html
61+
- title: Manual upgrade alternatives
62+
url: /docs/ca/devscu/manual-upgrade-alternatives/when-and-why-to-do-manual-upgrade.html
63+
nested:
64+
- title: When and why to do manual upgrade?
65+
url: /docs/ca/devscu/manual-upgrade-alternatives/when-and-why-to-do-manual-upgrade.html
66+
- title: Migration SDK
67+
url: /docs/ca/devscu/manual-upgrade-alternatives/migration-sdk.html

‎docs/ca/devscu/manual-upgrade-alternatives/migration-sdk.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
title: Migration SDK
3+
description: Learn how the open-source Migration SDK helps you plan and execute manual Spryker upgrades when the Spryker Code Upgrader cannot be used.
4+
template: howto-guide-template
5+
---
6+
7+
## Overview
8+
9+
The **Migration SDK** is an open-source, community-developed tool that assists you in planning and executing manual upgrades of Spryker projects.
10+
It analyzes your project and generates detailed reports, upgrade instructions, compatibility checks, and effort estimations.
11+
12+
Unlike the **Spryker Code Upgrader**, the Migration SDK does **not** modify your codebase or create merge requests.
13+
Instead, it provides the data and guidance you need to perform updates manually and safely.
14+
15+
{% info_block warningBox "Warning" %}
16+
The Migration SDK is a community-maintained tool. It is not officially supported or guaranteed by Spryker.
17+
Use it at your own discretion. Contributions are welcome on [GitHub](https://github.com/spryker-projects/migration-program-sdk).
18+
{% endinfo_block %}
19+
20+
---
21+
22+
## When to use the Migration SDK
23+
24+
Use the Migration SDK when:
25+
26+
- Your project was created before the 2022.04 release and cannot use the incremental upgrade model.
27+
- You do not have access or entitlement to the **Spryker Code Upgrader**.
28+
- You need to perform a one-time manual upgrade to align your project with the latest Spryker version.
29+
30+
{% info_block infoBox "Tip" %}
31+
After completing a manual upgrade using the Migration SDK, you can usually switch to the official **Spryker Code Upgrader** for future incremental updates.
32+
{% endinfo_block %}
33+
34+
---
35+
36+
## Key capabilities
37+
38+
The Migration SDK offers a collection of PHP console scripts that automate analysis and planning tasks for manual upgrades.
39+
The most useful capabilities include:
40+
41+
### Package analysis
42+
Identify outdated packages and generate reports that compare your current setup with the target Spryker version.
43+
This helps you understand which packages require major, minor, or patch updates.
44+
45+
### Update planning
46+
Generate a structured upgrade instruction in CSV format that groups packages into safe update batches.
47+
This allows developers to work in parallel and reduce the risk of dependency conflicts during updates.
48+
49+
### Effort estimation
50+
Estimate how complex the upgrade will be by scanning your project for custom extensions, PHP, and Twig overrides.
51+
The generated report helps you plan effort and identify risky or highly customized modules.
52+
53+
### Compatibility checks
54+
Detect potential compatibility issues, such as outdated PHP versions, missing plugins, or missing glossary keys.
55+
Use these reports to resolve incompatibilities before running updates.
56+
57+
---
58+
59+
## Typical workflow
60+
61+
1. Clone the [Migration SDK repository](https://github.com/spryker-projects/migration-program-sdk).
62+
2. Create a `config.ini` file based on the provided `config.dist.ini` template.
63+
3. Run the desired analysis or estimation scripts from the command line.
64+
4. Review the generated reports in the `outputs/` directory to plan your upgrade steps.
65+
5. Apply the upgrade changes manually based on the reports and upgrade instructions.
66+
67+
All scripts and configuration options are documented in detail in the [GitHub README](https://github.com/spryker-projects/migration-program-sdk).
68+
69+
---
70+
71+
## Example use cases
72+
73+
- **Project analysis:** Run the package analyzer to identify outdated modules before planning a major version upgrade.
74+
- **Upgrade planning:** Use the update instruction generator to divide your update process into manageable groups.
75+
- **Effort estimation:** Use the estimator report to predict development effort and prioritize modules.
76+
- **Compatibility validation:** Check for missing plugins or glossary entries to prevent regressions.
77+
78+
---
79+
80+
## Related documentation
81+
82+
- [When and why to use manual upgrade](index.html)
83+
- [Spryker Code Upgrader](/docs/ca/devscu/spryker-code-upgrader/index.html)
84+
- [Upgradability Guidelines](/docs/dg/dev/guidelines/keeping-a-project-upgradable/upgradability-guidelines/upgradability-guidelines.html)

‎docs/ca/devscu/manual-upgrade-alternatives/when-and-why-to-do-manual-upgrade.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
title: When and why to use manual upgrade
3+
description: Learn when to use manual upgrade instead of the Spryker Code Upgrader and how to streamline the process with the Migration SDK.
4+
template: howto-guide-template
5+
---
6+
7+
## Overview
8+
9+
The **Spryker Code Upgrader** is the primary and recommended tool for upgrading Spryker projects. It automates most upgrade steps, helping you keep your project aligned with the latest Spryker releases.
10+
However, in some cases, you might need to perform a **manual upgrade**. This guide explains when that is necessary and introduces tools that can simplify the manual upgrade process.
11+
12+
---
13+
14+
## When to use a manual upgrade
15+
16+
You might choose a manual upgrade in the following cases:
17+
18+
- **Legacy projects** – Your project was created before the 2022.04 release and is not compatible with the incremental upgrade model used by the Spryker Code Upgrader.
19+
- **Limited access** – You do not have entitlement or technical access to use the Spryker Code Upgrader.
20+
- **Custom upgrade strategy** – You prefer full control over upgrade steps or have a custom development workflow that does not align with automated upgrades.
21+
22+
---
23+
24+
## What to expect from manual upgrading
25+
26+
Manual upgrades require you to analyze version differences, identify breaking changes, and apply updates directly in your codebase.
27+
This process can take more time and effort than using the Spryker Code Upgrader, but it allows you to:
28+
29+
- Plan and execute upgrades at your own pace.
30+
- Review and validate each change manually.
31+
- Handle highly customized project setups that automated tools cannot process.
32+
33+
{% info_block infoBox "Tip" %}
34+
35+
Even when you perform a manual upgrade, follow the [Upgradability Guidelines](/docs/dg/dev/guidelines/keeping-a-project-upgradable/upgradability-guidelines/upgradability-guidelines.html) to keep your project compatible with future releases.
36+
37+
{% endinfo_block %}
38+
---
39+
40+
## How the Migration SDK can help
41+
42+
The **[Migration SDK](migration-sdk.html)** is an open-source, community-developed tool that assists with manual upgrades.
43+
It helps you plan and execute upgrades by providing:
44+
45+
- Compatibility and version comparison reports.
46+
- Detailed update instructions.
47+
- Effort and change estimations.
48+
49+
The Migration SDK does **not** modify your codebase or create merge requests. Instead, it helps you understand what needs to change before you start manual updates.
50+
51+
{% info_block warningBox "Warning" %}
52+
The Migration SDK is not officially maintained or supported by Spryker. It is provided as a community project and used at your own discretion.
53+
Contributions are welcome on [GitHub](https://github.com/spryker-projects/migration-program-sdk).
54+
{% endinfo_block %}
55+
---
56+
57+
## Next steps
58+
59+
- Learn more about the [Migration SDK](migration-sdk.html).
60+
- Read the [Upgradability Guidelines](/docs/dg/dev/guidelines/keeping-a-project-upgradable/upgradability-guidelines/upgradability-guidelines.html) to keep your project easier to upgrade in the future.
61+
- Review the [Spryker Code Upgrader](/docs/ca/devscu/spryker-code-upgrader/index.html) if your project meets the requirements for automated upgrades.

‎docs/ca/devscu/spryker-code-upgrader.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,11 @@ You can change the upgrade schedule to better fit your development process.
4343

4444
The Upgrader is shipped with PaaS+ in the EU and US regions.
4545

46+
{% info_block infoBox "Tip" %}
47+
Cannot use the Spryker Code Upgrader?
48+
Explore our open-source [Migration SDK](manual-upgrade-alternatives/migration-sdk.html) for planning and executing manual upgrades.
49+
{% endinfo_block %}
50+
4651
## Next steps
4752

4853
[How Spryker Code Upgrader works](/docs/ca/devscu/how-spryker-code-upgrader-works.html)

0 commit comments

Comments
 (0)