# Marko Upgrade

## Current state

| Feature | Marko 3 | Marko 4 | Marko 5 | Marko 6 |
| ---------------- | ------- | ------------------ | ------------ | ------------ |
| Support | ❌ | ✅ (Maintenance) | ✅ (Active) | 🔜 |
| Widgets | ✅ | ✅ (Compatibility) | ❌ | ⚠️ (Planned) |
| Class Components | ❌ | ✅ | ✅ | ⚠️ (Planned) |
| Tags API | ❌ | ❌ | ✅ (Preview) | ✅ |

pie 
    title Marko Apps by Version
    "v3 & older": 12
    "v4 w/ Widget compat" : 133
    "v4 no compat" : 54
    "v5" : 25

_(data pulled from http://go/nodedash, not 100% reliable)_

## Proposed state

| Feature | Marko 3 | Marko 4 | Marko 5 | Marko 6 |
| ---------------- | ------- | ---------- | ----------- | -------- |
| Support | ❌ | ❌ | ✅ | ✅ |
| Widgets | ✅ | ✅ (Compat) | ✅ (Compat) | ❌ |
| Class Components | ❌ | ✅ | ✅ | ❌ |
| Tags API | ❌ | ❌ | ✅ | ✅ |

## Goals

### All Apps Support TagsAPI

_Stretch Goal: all components on Tags API_

#### Benefits
- Apps can begin converting widgets/components one-by-one
- Performance/DX/APIs of shared components not limited by supporting older versions of Marko

#### Challenges
- No version of Marko currently supports all 3 APIs
- Option 1: require apps to get off Widgets
- **Option 2: add Widget compatibility to v5
_(probably best option: least likely to introduce friction for apps)_**
- Option 3: add Widget + Class compatibility to v6
- TagsAPI preview stable release
- Option 1: update preview to reach parity with Marko 6
- **Option 2: embed Marko 6 as the TagsAPI preview
_(probably best option: less friction when moving to Marko 6 proper, perf benefits today)_**
- Need documentation for TagsAPI
- Need guides for Widget → TagsAPI and Class → TagsAPI

### All Apps on `@marko/run`

_Baseline Goal: all existing webpack apps on `@marko/run`_

#### Benefits
- Faster iteration for apps (hot module reloading)
- Sunset Lasso & Webpack support
- Shared architecture between eBay apps & open source

#### Challenges
- Dropping Lasso
- Bundling on CI rather than at runtime may have subtle impacts
- Remove use of `browser.json`
- Remove use of flags (replace with `arc` or dynamic entries)
- Likely requires migrating away from Widgets
- May want tooling that reads `routes.json` and generates an appropriate file structure

## Dependency order

While alternative paths exist if we want to prioritize some later goals of the graph, this is the most efficient path to "Modern Marko".

flowchart TD
    subgraph Legend
    K1(["Marko Team Task"])
    K2["App Devs Task"]
    K3{"Milestone"}
    end

flowchart TD
    A["Update v4 (no compat)"] --> D
    B([Widget compat in v5]) --> C
    C["Update v4 w/ compat"] --> D
    D{All Apps on v5} ---> G
    F([v6 as TagsAPI in v5]) --> G
    G{All Apps\nsupport TagsAPI} --> H & I
    X(["Migration tooling?"]) -.-> H
    H["Widgets → TagsAPI"] ---> J
    Y(["Migration tooling?"]) -.-> I
    I["ClassComponents → TagsAPI"] ---> M
    J{All Apps\nWidgetless} ---> K & M
    K[Remove browser.json] ---> L
    L["All apps on @marko/run"] ---> N
    M{All Apps\non TagsAPI} ---> N
    N{All Apps\non Modern Marko}

## Additional Thoughts

### For apps on v4 with no compat...

- Significant number of these (24%)
- Should be nothing blocking the upgrade
- Should be a painless upgrade (`npm i marko@^5` and everything works 🤞)
- Why have they not upgraded? Are there any issues with the v4 to v5 upgrade we're unaware of?

### Adding Widget compat to v5

While we could try to go straight to v6 with compat for Widgets/Class, it probably makes the most sense to bring forward the Widget compat layer from v4 to v5.
- Marko 5 is stable & released
- v4 & v5 share essentially the same runtime
- **This means that apps on v4 should be able to update to v5 without any changes/issues.**

### Embedding v6 as the TagsAPI in v5
- nearly no risk of breakage when moving to v6 if everything is on the TagsAPI
- get both the perf/dx benefits of Marko 6 in Marko 5 (for components/islands on the TagsAPI)
- Updates to Marko 6 also received by TagsAPI components

### Compat for Widgets/Class in v6?

**_If_** we get everyone on Marko 5 with access to the TagsAPI (Marko 6), it might make sense for that to be the holding place for apps that aren't fully on the TagsAPI, rather than adding compat to Marko 6.

At least de-prioritize?

### Converting from Widgets/Class to TagsAPI

#### Steps
1. Audit component tests
- Tests should ideally be using `@marko/testing-library` (only ~20% of apps currently)
- Tests should not be testing component/widget internals
2. One component at a time, migrate to TagsAPI
- Should be able to keep existing component tests (_if they're not testing internals_)

#### Migration tooling options

1. None
2. AST-based
3. AI-based

### Prioritization

#### Apps

1. Apps on Marko 5
- Opens up the ability of shared modules to use TagsAPI
- Should be a painless upgrade (`npm i marko@^5` and everything works 🤞)
2. Widgets → TagsAPI
- Widgets are the major blocker in getting off Lasso (and therefore to adopting `@marko/run`)
3. All Shared Components → TagsAPI
- Benefit multiple apps
4. Apps on `@marko/run`
5. All App Components → TagsAPI
- How to ensure that teams prioritize upgrading _all_ components (get this whole effor across the finish line)?

#### Marko Team

1. Widget compat in v5
- Should allow all existing Marko v4 apps to upgrade w/o changes
2. Embedding v6 as the TagsAPI in v5
- Gets Marko 6 benefits to applications earlier
- Allows apps/shared modules to use latest APIs
3. `@marko/run` migration tooling
- Apps already on Marko v5 & webpack should be able to migrate fairly easily
- (maybe higher priority)
6. Widget migration tooling
7. Class migration tooling

### Deadline Options

1. Give all teams an upgrade deadline
- Simple, easy to implement
- If all teams are working on it at once it may be encouraging for engineers

2. Work with a few teams at a time, small to big
- Small teams allow us to work out kinks with migration scripts
- More directed attention from our team for support requests

3. Work with a few teams at a time, starting with those which are most often listed as dependencies
- We can be more agressive about teams moving to the tags API even _without_ a compatability layer, because we start with the projects that don't have dependencies

### Apps on Marko v3

Those apps that are still on Marko v3 or older are assumed to be in an end-of-life stage as they would have needed to file for an exception to the Marko v4 upgrade. We should double check this, but we are under the assumption that these apps will not be upgrading to v5.