upgrade-notes-analyzer

Upgrade Notes Analyzer

Analyzes PR diffs to identify breaking changes, feature movements, and scope.

Input

• Complete diff content & commit messages (from pr-diff-fetcher)
• PR metadata (title, base branch, labels)
• User-specified scope (optional: backend|storefront|both)

Analysis Order (CRITICAL)

⚠️ STEP 1: MOVEMENTS FIRST

A deletion in /project-base/ + addition in /packages/ = MOVEMENT, not removal!

Detection:

1. Check commit messages for: "move", "moved", "moving" + "project-base"/"packages"
2. Cross-reference every /project-base/src/ deletion with /packages/ additions:
   • Same class name + namespace change (App\* → Shopsys\FrameworkBundle\*) = MOVEMENT
   • Similar path structure = likely MOVEMENT

Output:

- [features moved](#movement-of-features-from-project-base-to-packages) from project-base to the {package} package:
    - {description} ({new FQCN from packages})

STEP 2: DELETIONS (only after ruling out movements)

Always BC breaks:

• Methods removed from /packages/ classes
• Classes/interfaces removed entirely (no corresponding addition)
• GraphQL queries/mutations/fields removed
• Configuration options removed

Output:

- method `{methodName}` in `{FQCN}` was removed - use `{replacement}` instead
- GraphQL field `{Type}#{field}` has been removed

STEP 3: MODIFICATIONS

Constructor Changes (CRITICAL RULE):

• ❌ SKIP autowired services (facades, repositories, factories) - DI handles automatically
• ✅ INCLUDE manually instantiated classes (with new): FilterQuery, DataObject, form types, validators

Identify manually instantiated: Search diff for new ClassName() usage

Other modifications:

• Method signature changes (parameters, types)
• Property/interface changes
• GraphQL schema changes (field types, arguments)
• Configuration structure changes

Output:

- `{FQCN}` constructor now has new required `$param` parameter
  - this class is manually instantiated, update all `new {ClassName}()` calls

STEP 4: ADDITIONS (mostly skip)

SKIP:

• ❌ New methods/properties/classes in /packages/
• ❌ New migrations (auto-executed)
• ❌ Constructor params in autowired services

INCLUDE:

• ✅ Corresponds to project-base deletion (it's a MOVEMENT - see Step 1)
• ✅ Manual setup required (database extensions, SQL)
• ✅ Constructor params in manually instantiated classes

STEP 5: SCOPE

Infer from paths:

• backend: /packages/, /project-base/app/, /project-base/templates/
• storefront: /project-base/storefront/
• both: GraphQL schema changes (*.types.yaml, *Query.php) + storefront usage

Output Format

## Analysis Results

### Scope
**Determined scope:** {backend|storefront|both}
**Confidence:** {high|medium|low}
**Reasoning:** {brief explanation}

### Movements Detected
{count} movements from project-base to packages:
- **{Feature}**: `{old}` → `{new FQCN}` ({package})

### Breaking Changes ({total count})

#### Removals ({count})
- `{FQCN}::{method}` removed → use `{replacement}`

#### Modifications ({count})
- `{FQCN}` constructor: new required `$param` (manually instantiated)

#### GraphQL ({count})
- Field `{Type}#{field}` removed

#### Configuration ({count})
- Parameter `{old}` renamed to `{new}`

### Content for Upgrade Notes

#### {PR Title} ([#{PR_NUMBER}](https://github.com/shopsys/shopsys/pull/{PR_NUMBER}))

- {actionable instruction 1}
- {actionable instruction 2}
- see #project-base-diff to update your project

Writing Rules

INCLUDE (only if developer action is required):

• Methods/properties/classes removed → show replacement
• Signatures changed → show before/after
• Manual actions required (DB extensions, etc.)
• Feature movements to packages

EXCLUDE:

• New entities/classes/methods/routes/fields (additions never break existing code)
• New migrations (auto-executed)
• Constructor changes in autowired services
• Feature explanations, descriptions, or context about what was built
• Any line that merely describes what was added/created without requiring developer action

Style:

• Upgrade notes are instructions, not a changelog — every line must tell the developer what to DO, not what happened
• Action verbs: "use", "replace", "update", "rename"
• Always use FQCN
• Never describe new features — if something was added and requires no action, omit it entirely
• If a method/class was renamed (same purpose, new name), say "was renamed to", NOT "was removed, use X instead"
• When listing alternatives, use "or" not semicolons (e.g., "use X instead or use Y to populate all at once")
• Key test: "Does the developer need to change their code?" → YES = include, NO = omit

Code example formatting:

• Use ```diff ``` for code blocks (preferred styling)
• Use markdown tables for simple value mappings/replacements (e.g., old method → new method)
• Show actual code from commits as examples, not generic placeholders

Critical:

• MOVEMENTS FIRST - never mark movement as "removed"
• FQCN ALWAYS
• - see #project-base-diff to update your project - ONLY if there were any changes in project-base/ folder
• Constructor changes - ONLY for new ClassName(), NOT autowired

Real-World Example Patterns:

Pattern 1: Simple project-base only (no BC breaks)

#### Upgrade postgreSQL version to 17.4 ([#3659](https://github.com/shopsys/shopsys/pull/3659))

- see #project-base-diff to update your project

Pattern 2: Method/property removal with replacement

#### Admin Grid performance improvements ([#2460](https://github.com/shopsys/shopsys/pull/2460))

- Twig filter `getProductListDisplayName` from `ProductExtension` is removed. Use `getProductListDisplayNameByName` instead.
- method `getStoresCountByDomainId` in `StoreFacade` and `StoreRepository` in framework package was removed
- see #project-base-diff to update your project

Pattern 3: Constructor/method signature changes

#### enable domain configuration with path fragment ([#4113](https://github.com/shopsys/shopsys/pull/4113))

- `Shopsys\FrameworkBundle\Component\Domain\Config\DomainConfig` constructor now has new required `$baseUrl` and optional `$postfix` parameters
    - `DomainConfig::getUrl()` method returns the whole URL including the postfix, if you need just the host part, use `DomainConfig::getBaseUrl()` method instead
- `Shopsys\FrameworkBundle\Twig\ImageExtension::getImageUrl()` method now requires `int $domainId` parameter
- see #project-base-diff to update your project

Pattern 4: Feature movement from project-base to packages

#### movements of features from project-base to packages ([#3735](https://github.com/shopsys/shopsys/pull/3735))

- [features moved](#movement-of-features-from-project-base-to-packages) from project-base to the framework package:
    - `CspHeaderController` and all the related logic (see the usages of `Setting::CSP_HEADER` constant)
    - `FlagController` - `editAction`, `newAction`, `deleteAction`, `deleteConfirmAction`, and all the related logic
    - whole language constant agenda in admin (see `LanguageConstantController`)
    - `Product::$productVideos` property, `ProductVideo` entity, and all the related logic
- [features moved](#movement-of-features-from-project-base-to-packages) from project-base to the frontend-api package:
    - `Breadcrumb` interface graphql type (`BreadcrumbDecorator.types.yaml`)
    - language constant types and query (`LanguageConstantQuery` and `LanguageConstantDecorator.types.yaml`)
- see #project-base-diff to update your project

Pattern 5: Conditional instructions (if you have X)

#### Grids ordering by administrator language ([#4135](https://github.com/shopsys/shopsys/pull/4135))

- added new factories for all DataSource types to ensure consistent instantiation
- if you are using custom grid implementations with direct DataSource instantiation, use the new factory classes for consistent collation behavior
- see #project-base-diff to update your project

Pattern 6: Database/infrastructure manual actions

#### Admin Grid performance improvements ([#2460](https://github.com/shopsys/shopsys/pull/2460))

- add to `pg_trgm` extension to your postgreSQL database
    - you need to install the extension before running the migration `Version20241205144230`
    - for your production and devel environment, you need to install the extension manually (`CREATE EXTENSION IF NOT EXISTS pg_trgm WITH SCHEMA pg_catalog`)
    - localhost and CI is covered by `db-create` target
- check your code for usages of the `NORMALIZED(columnName) LIKE NORMALIZED(:text)` and create the indexes for corresponding columns
- see #project-base-diff to update your project

Pattern 7: GraphQL schema changes

#### remove linked categories ([#3718](https://github.com/shopsys/shopsys/pull/3718))

- Frontend API field `Category#linkedCategories` has been removed along with its loader
- if your project uses this functionality
    - skip the migration `Shopsys\FrameworkBundle\Migrations\Version20250324141622`
    - skip removing the code
    - add the field `linkedCategories` to the `Category` type in your project in Frontend API schema
- see #project-base-diff to update your project

Pattern 8: Storefront changes (components, hooks, types)

#### enable domain configuration with path fragment ([#4113](https://github.com/shopsys/shopsys/pull/4113))

- **`getDomainConfig()` function signature changed**
    - before: `getDomainConfig(domainUrl: string): DomainConfigType`
    - after: `getDomainConfig(context: GetServerSidePropsContext | NextPageContext): DomainConfigType`
- **`createClient()` function signature changed**
    - before: accepts `publicGraphqlEndpoint: string` parameter
    - after: accepts `domainConfig: DomainConfigType` parameter instead
- see #project-base-diff to update your project

Pattern 9: Configuration changes

#### enable domain configuration with path fragment ([#4113](https://github.com/shopsys/shopsys/pull/4113))

- `Shopsys\FrameworkBundle\Component\Context\AdminContext` constructor parameter `$adminRoutePrefixes` has been renamed to `$additionalAdminPathPrefixes`
    - the meaning of the parameter has changed, it now represents additional path prefixes instead of the original route names
    - the configuration parameter name has changed from `admin_context_route_prefixes` to `admin_context_additional_path_prefixes`
- see #project-base-diff to update your project

Pattern 10: Multiple related changes

#### Implement store features ([#3413](https://github.com/shopsys/shopsys/pull/3413))

- `StoresQuery` class now uses new `StoreFacade` class from frontend-api package
    - Instead of `getStoresByDomainId` method, use `getFilteredStores` method
    - Instead of `getStoresCountByDomainId` method, use `getFilteredStoresCount` method
- attribute `Store::$contactInfo` was removed. If you still want to use it, you need to implement it by yourself
- new attributes `Store::$email`, `Store::$phone` and `Store::$directions` were introduced
- `StoreFormType` form was refactored into multiple groups. Look into the `StoreFormType` class to see the changes
- see #project-base-diff to update your project