Dokumentacja projektu - co musi zawierać
Dokumentacja nie musi być długa, ale musi odpowiadać na pytania, które nowa osoba zada w pierwszym tygodniu. W projektach sklepów najlepiej sprawdza się kilka krótkich dokumentów trzymanych w repozytorium obok kodu:
| Dokument | Co zawiera | Kiedy się przydaje |
|---|
| Instrukcja uruchomienia | Wymagane wersje oprogramowania, kroki instalacji lokalnej i na stagingu | Pierwszy dzień nowego wykonawcy |
| Instrukcja wdrożenia | Jak kod trafia na produkcję, kopia przed wdrożeniem, plan cofnięcia | Każda zmiana na sklepie |
| Mapa integracji | Systemy, kierunki przepływu danych, częstotliwość, sposób uwierzytelnienia | Awaria lub zmiana w API dostawcy |
| Rejestr dostępów | Konta, klucze, aplikacje, właściciel i miejsce przechowywania | Przejęcie i wymiana dostępów |
| Zadania cykliczne | Crony, kolejki, scenariusze automatyzacji, godziny uruchomienia | Diagnoza brakujących danych |
| Znane problemy | Błędy, obejścia, długi techniczny, zaplanowane migracje | Planowanie prac na kolejne miesiące |
Szczególnie cenna jest lista znanych problemów. Każdy projekt ma miejsca, o których autor wie, że są kruche: moduł, który nie przetrwa aktualizacji platformy, integracja, która gubi zamówienia przy dużym ruchu, skrypt uruchamiany ręcznie raz w miesiącu. Programista odchodzący w dobrej atmosferze chętnie to spisze, a nowy wykonawca zaoszczędzi na tym wiele godzin. Dokumentację trzymaj w repozytorium lub w firmowym systemie wiedzy, a nie w prywatnych notatkach wykonawcy.
Dostępy - jak je przejąć i bezpiecznie wymienić
Dostępy to najbardziej czasochłonna część przekazania, bo są rozproszone po wielu usługach. Zacznij od spisania, gdzie programista ma konto lub klucz, a potem dla każdego miejsca ustal, czy konto należy do firmy, czy do programisty. Typowa lista dla sklepu wygląda tak:
Domena i DNS - konto u rejestratora i dostawcy DNS, dane do faktur i odnowień.
Hosting i serwery - panel hostingu, SSH, bazy danych, kopie zapasowe.
Repozytorium i narzędzia - repozytorium kodu, automatyczne wdrożenia, monitoring błędów.
Panel sklepu - konto administratora lub konto współpracownika, aplikacje i moduły z licencjami.
Marketplace'y - aplikacje zarejestrowane w portalach deweloperskich i powiązania z kontami sprzedawcy.
Płatności, kurierzy, faktury - klucze API, konta w panelach deweloperskich i sandboxach.
Automatyzacje - konta w narzędziach typu Make lub n8n, integrator, skrypty w chmurze.
W Shopify zewnętrzni wykonawcy pracują zwykle na kontach współpracowników. Według centrum pomocy Shopify współpracownik wysyła prośbę o dostęp z czterocyfrowym kodem, który właściciel znajduje w sekcji bezpieczeństwa na stronie użytkowników, konta współpracowników nie wliczają się do limitu użytkowników sklepu, a usuwa się je w Ustawieniach, w sekcji Użytkownicy (stan na sierpień 2026 - sprawdź aktualną pomoc Shopify). Przy zmianie wykonawcy nowy partner wysyła własną prośbę, a dostęp poprzedniego usuwa się po zakończeniu przekazania.
Osobną sprawą są aplikacje w portalach marketplace'ów. Tokeny Allegro są wydawane dla konkretnej aplikacji, a nie dla sklepu, więc nowy wykonawca zwykle rejestruje własną aplikację i potrzebuje nowej autoryzacji konta. Szczegóły opisujemy we wpisie token API Allegro - jak go odnawiać i dlaczego integracja przestaje działać.
[#uwaga] Po przekazaniu projektu wymień wszystkie hasła, klucze API i sekrety, które znał poprzedni wykonawca, nawet jeśli współpraca kończy się w dobrej atmosferze. Rób to w kolejności: nowy klucz, podmiana w konfiguracji, sprawdzenie w logach, odebranie starego. Procedurę opisujemy we wpisie klucze API i uprawnienia w sklepie.
Konfiguracja, licencje i zadania cykliczne
Między kodem a dostępami jest warstwa, o której łatwo zapomnieć: konfiguracja środowisk i wszystko, co dzieje się w sklepie bez udziału człowieka. To właśnie jej brak najczęściej wychodzi kilka tygodni po przekazaniu, gdy nagle nie generuje się raport, nie odświeża feed albo nie przedłuża licencja modułu. Przy przekazaniu poproś o:
Listę zmiennych środowiskowych i plików konfiguracyjnych dla każdego środowiska, z opisem, do czego służą, ale bez wartości sekretów w samej dokumentacji.
Listę zadań cron i kolejek z godzinami uruchomienia, czasem trwania i informacją, co się dzieje, gdy zadanie się nie wykona.
Listę płatnych modułów, motywów i aplikacji z informacją, na kogo jest wystawiona licencja i kiedy się odnawia.
Opis konfiguracji pamięci podręcznej, serwera i zadań, które trzeba wykonać po wdrożeniu, np. czyszczenie cache lub przebudowa indeksów.
Skrypty jednorazowe i pomocnicze, np. do importu danych czy poprawek w bazie, z opisem, kiedy były uruchamiane.
Licencje zasługują na osobną uwagę. Moduł kupiony na prywatne konto programisty może przestać otrzymywać aktualizacje po zakończeniu współpracy, a jego przeniesienie bywa niemożliwe bez kontaktu z autorem. Przy przekazaniu ustal, które licencje trzeba przenieść lub kupić ponownie na firmę, zanim stara wygaśnie.
Najczęstsze braki przy przekazaniu projektu sklepu
W przejmowanych projektach powtarzają się te same luki. Najczęściej brakuje aktualnej wersji kodu, bo ostatnie poprawki zostały tylko na serwerze, instrukcji wdrożenia, bo programista robił je z pamięci, oraz informacji, na jakim koncie działają usługi zewnętrzne, np. narzędzie do automatyzacji, w którym zbudowano przepływ zamówień do programu fakturowego. Często brakuje też danych dostępowych do sandboxów, więc nowy wykonawca nie może bezpiecznie testować integracji i musi zakładać konta od nowa.
Drugą grupą braków są decyzje, których nikt nie zapisał. Dlaczego zamówienia z jednego kanału są pomijane w eksporcie do ERP, dlaczego stan magazynu jest pomniejszany o stałą wartość, dlaczego jedna metoda dostawy ma ręcznie wpisany wyjątek w kodzie. Bez odpowiedzi nowy wykonawca albo boi się takich miejsc dotykać, albo poprawia je w dobrej wierze i psuje ustalenia, które miały sens. Dlatego przed zakończeniem współpracy warto przejrzeć z poprzednim programistą nietypowe fragmenty kodu i zapisać krótkie uzasadnienie przy każdym z nich.
Przekazanie projektu krok po kroku
Przekazanie najlepiej zaplanować jako krótki projekt z harmonogramem i osobą odpowiedzialną po stronie sklepu. Gdy stary i nowy wykonawca pracują przez chwilę równolegle, większość pytań da się wyjaśnić na bieżąco. Kolejność, która sprawdza się w projektach sklepów:
[#chart:wpr83b]
Okres równoległej pracy nie musi być długi. Wystarczy, że obejmie jeden pełny cykl typowych zadań sklepu, np. comiesięczne zadania cykliczne, i jedno wdrożenie przeprowadzone przez nowego wykonawcę pod okiem poprzedniego. Jeśli poprzedni programista jest dostępny tylko przez kilka godzin, wykorzystaj je na pytania o listę znanych problemów i nietypowe zadania cykliczne, a nie na rzeczy, które da się wyczytać z kodu.
Jak sprawdzić, że przekazanie projektu jest kompletne
Najlepszym testem jest odtworzenie projektu na czystym środowisku. Nowy wykonawca pobiera kod z repozytorium, uruchamia go według instrukcji, podłącza sandboxy integracji, wdraża drobną zmianę na staging i produkcję według instrukcji wdrożenia. Każde miejsce, w którym musi zapytać poprzednika, to luka w przekazaniu. Pomocne jest proste rozróżnienie:
[#chart:wpr83c]
Wynik testu warto zapisać w protokole odbioru: lista otrzymanych elementów, wykryte braki i termin ich uzupełnienia. Jeśli płatność za ostatni okres współpracy jest powiązana z odbiorem przekazania, obie strony mają jasny moment zamknięcia sprawy. Protokół przyda się też za rok, gdy trzeba będzie ustalić, kiedy i od kogo przejęto dany fragment projektu i jakie były wtedy znane ograniczenia.
Przekazanie projektu w umowie z programistą
Najłatwiej przekazać projekt, który od początku był prowadzony z myślą o przekazaniu. Dlatego warunki warto zapisać już w umowie lub zleceniu: repozytorium na koncie firmy, dokumentacja jako część odbioru każdego etapu, konta techniczne zakładane na firmę, okres pomocy po zakończeniu współpracy i jej zasady. Jak przygotować zlecenie z zakresem i kryteriami odbioru, opisujemy we wpisie zlecenie integracji programiście - brief, zakres i kryteria odbioru. Kwestie praw autorskich do kodu, licencji i powierzenia przetwarzania danych osobowych skonsultuj z prawnikiem.
Gdy przekazanie odbywa się w trudnej sytuacji, np. programista przestał odpowiadać, zacznij od zabezpieczenia tego, co masz: pełnej kopii serwera i bazy, haseł do kont, które są na firmę, i listy integracji, które działają. Następnie odzyskuj kontrolę nad kluczowymi kontami przez procedury dostawców, odbierz dostępy, które możesz odebrać, i dopiero potem zleć analizę kodu z serwera. Taka kolejność chroni sprzedaż, zanim zaczniesz porządkować projekt.
Jak Vinson pomaga przy przekazaniu projektu
Zapewniamy wsparcie programistyczne dla sklepów i sprzedawców: integracje, automatyzacje, poprawki i rozwój sklepów oraz narzędzi. Przejmujemy projekty sklepów i integracji od innych wykonawców: przygotowujemy listę kontrolną przekazania, porównujemy kod z serwera z repozytorium, odtwarzamy projekt na stagingu, uzupełniamy dokumentację i przeprowadzamy wymianę kluczy bez przestoju. Szczegóły znajdziesz na stronie Wsparcie programistyczne dla e-commerce.
Najczęściej zadawane pytania
Co powinien przekazać programista po zakończeniu współpracy?
Kod źródłowy z historią w repozytorium firmy, instrukcję uruchomienia i wdrożenia, mapę integracji, rejestr kont i kluczy API, opis zadań cyklicznych oraz listę znanych problemów. Do tego dostępy do wszystkich usług, w których działa projekt, przeniesione na konta firmy.
Jak sprawdzić, czy dostałem kompletny kod sklepu?
Poproś nowego wykonawcę, żeby postawił projekt na czystym środowisku według instrukcji i porównał kod z repozytorium z kodem działającym na serwerze. Różnice i miejsca, w których trzeba pytać poprzednika, to braki do uzupełnienia.
Czy po zmianie programisty trzeba zmieniać klucze API?
Tak. Każdy klucz, hasło i sekret, który znał poprzedni wykonawca, warto wymienić, nawet przy dobrym zakończeniu współpracy. Najpierw wygeneruj nowy klucz i podmień go w konfiguracji, sprawdź w logach, że działa, a dopiero potem odbierz dostęp staremu.
Co zrobić, gdy repozytorium jest na koncie programisty?
Poproś o przeniesienie repozytorium do organizacji lub na konto firmy. Na GitHubie przeniesienie zachowuje m.in. zgłoszenia i pull requesty, a stare linki są przekierowywane. Jeśli to niemożliwe, poproś o pełną kopię repozytorium z historią, nie tylko o bieżące pliki.
Czy integracja z Allegro zadziała po zmianie wykonawcy?
Zależy, czyja jest aplikacja w portalu Allegro dla deweloperów. Jeśli zarejestrował ją poprzedni wykonawca, nowy zwykle tworzy własną i ponownie autoryzuje konto sprzedawcy. Po uruchomieniu nowej integracji usuń starą aplikację z listy powiązanych aplikacji w Moje Allegro.
Dobrze przeprowadzone przekazanie projektu od programisty to kilka dni pracy, które oszczędzają miesiące odtwarzania wiedzy. Jeśli zmieniasz wykonawcę albo chcesz uporządkować dokumentację i dostępy w swoim sklepie, sprawdź wsparcie programistyczne Vinson.
