---
name: sdk-version-upgrade
description: Podniesienie wersji SDK lub biblioteki wraz z migracją wywołań API - planowanie zmiany, kolejność edycji, obsługa breaking changes i kryteria akceptacji. Użyj gdy zadanie mówi o bumpie wersji, upgradzie SDK, migracji do nowego major release lub usunięciu deprecated API.
license: Apache-2.0
allowed-tools:
  - read_file
  - search_repo
  - list_files
  - write_file
  - replace_in_file
  - run_verification
metadata:
  owner: pubi-platform
  version: "1.0.0"
  references: acme-sdk-2.x-migration.md
---

# Upgrade wersji SDK

## Zasada nadrzędna

Upgrade to **dwie rozłączne zmiany**: (a) deklaracja wersji w pliku zależności,
(b) dostosowanie kodu do nowego API. Deklarację wersji ustawia deterministycznie silnik pipeline'u -
Twoim zadaniem jest wyłącznie (b). Nie edytuj ręcznie plików zależności, chyba że plan mówi inaczej.

## Kolejność pracy

1. Przeczytaj notatkę migracyjną dla docelowej wersji z katalogu `references/` tego skilla.
   Jeśli brakuje notatki dla danej biblioteki - **zatrzymaj się** i zgłoś `requires_human`.
   Nie migruj API "z pamięci modelu".
2. Zbuduj mapę zmian: `stary symbol -> nowy symbol -> plik(i) do zmiany`.
3. Edytuj plik po pliku, najmniejszą możliwą zmianą (`replace_in_file`, nie przepisywanie pliku).
4. Po każdym pliku uruchom weryfikację (`run_verification`). Czerwony wynik naprawiaj natychmiast,
   zanim przejdziesz dalej - kumulowanie błędów uniemożliwia ustalenie przyczyny.
5. Na koniec sprawdź, czy nie zostały użycia starego API: `search_repo` po każdym symbolu z mapy.

## Breaking changes - reguły decyzyjne

| Sytuacja | Działanie |
|---|---|
| Zmiana nazwy klasy/metody, ta sama semantyka | Migruj bezpośrednio |
| Zmiana nazw parametrów | Migruj, zachowując wartości wywołań 1:1 |
| Zasób wymaga teraz zamknięcia / context managera | Użyj `with`, nie dodawaj ręcznego `close()` |
| Nowy wymagany parametr bez sensownej wartości domyślnej | `requires_human` - to decyzja biznesowa |
| Usunięta funkcjonalność bez zamiennika | `requires_human`, nie obchodź problemu własną implementacją |

## Kryteria akceptacji

- Wszystkie testy repozytorium zielone.
- Zero wystąpień starych symboli poza plikami changelog/dokumentacji.
- Diff nie zawiera zmian niezwiązanych z migracją.
- Deklarowana wersja zależności odpowiada wersji docelowej z zadania.