Cel czytelnika: jak nie utopić projektu w chaosie repozytoriów
Osoba prowadząca projekt społecznościowy zwykle ma dwa problemy naraz: mało czasu i ograniczoną energię wolontariuszy. Struktura repozytoriów – monorepo czy multirepo – decyduje, czy ta energia pójdzie w rozwój funkcji, czy w walkę z narzędziami i niejasnym workflow.
Strategia wyboru między monorepo a multirepo powinna być podporządkowana jednemu: możliwie prostemu onbordingowi, czytelnemu podziałowi odpowiedzialności i minimalizacji kosztów utrzymania, zwłaszcza przy rotacji wolontariuszy.
Czym w ogóle jest monorepo i multirepo w kontekście projektu społecznościowego
Monorepo – jeden dom dla całego projektu
Monorepo oznacza, że cały kod projektu społecznościowego żyje w jednym repozytorium. Frontend, backend, skrypty devopsowe, dokumentacja, a czasem nawet konfiguracje infrastruktury – wszystko w jednym miejscu, zazwyczaj w osobnych katalogach.
Na GitHubie wygląda to jako jedno widoczne repo, np. github.com/organizacja/projekt, a w środku struktura typu:
/frontend – aplikacja webowa lub mobilna
/backend – API, serwisy
/docs – dokumentacja, guide’y dla użytkowników i kontrybutorów
/infra – pliki CI/CD, Terraform, Ansible itp.
/scripts – narzędzia pomocnicze
W projektach społecznościowych to podejście kusi prostotą: jedno repo do oznaczenia gwiazdką, jedno do zforkowania, jedno do obserwowania. Łatwiej też „złapać” kogoś nowego – wysyłasz tylko jeden link.
Multirepo – wiele mniejszych, wyspecjalizowanych repozytoriów
Multirepo to podejście, w którym kod dzielony jest na kilka lub kilkanaście osobnych repozytoriów, zwykle według funkcji lub technologii. Każde repozytorium ma własną historię, zgłoszenia błędów, pull requesty i proces wydań.
Przykładowa organizacja na GitHubie może wyglądać tak:
github.com/organizacja/projekt-frontend
github.com/organizacja/projekt-backend
github.com/organizacja/projekt-mobile
github.com/organizacja/projekt-docs
github.com/organizacja/projekt-infra
Dla projektu społecznościowego takie rozbicie bywa wygodne, gdy masz różne podzespoły (np. osobno frontendowcy, osobno DevOps, osobno ludzie od dokumentacji) i chcesz dać im dużą autonomię: inne reguły pracy, inne tempo releasów, inny poziom „formalistyczności”.
Specyfika projektów społecznościowych a wybór struktury repozytorium
W projektach firmowych strukturę repo dyktuje często architekt, CTO czy korporacyjne standardy. W projekcie społecznościowym realia są inne:
różny poziom doświadczenia – od osób, które pierwszy raz widzą GitHuba, do seniorów próbujących „odbić się od pracy”;
rotacja wolontariuszy – część ludzi pojawia się na kilka tygodni, potem znika; dokumentacja i prosty workflow są cenniejsze niż wyrafinowana architektura;
wiele ról – developerzy, tłumacze, osoby od UX, od treści, od testowania, od social mediów. Nie każdy musi umieć klonować repo i odpalać Docker Compose;
działanie po godzinach – nikt nie siedzi 8 godzin dziennie nad kodem, więc narzędzia muszą być maksymalnie mało frustrujące.
Z tego powodu struktura monorepo czy multirepo w projekcie open source musi być oceniana przez pryzmat: jak szybko ktoś z zewnątrz znajdzie miejsce, gdzie może realnie pomóc, bez ton dokumentacji i konfiguracji.
Dlaczego wybór między monorepo a multirepo ma tak duże znaczenie
Decyzja monorepo vs multirepo wpływa bezpośrednio na:
onboarding kontrybutorów – ile kroków trzeba wykonać, żeby znaleźć zadanie, przygotować środowisko i wysłać pierwszy PR;
tempo zmian – czy jedna zmiana w API wymaga koordynacji z trzema innymi repozytoriami, czy wystarczy jeden pull request;
koszty utrzymania – ile pipeline’ów CI trzeba utrzymać, ile razy aktualizować te same szablony issue, ile robotów (botów) konfigurować oddzielnie;
odporność na chaos – czy łatwo „oddać” odpowiedzialność za fragment projektu małemu zespołowi, czy wszystko kończy się na jednej osobie, która ogarnia całe monorepo.
Im mniej czasu i pieniędzy ma społeczność, tym ważniejsze, żeby struktura repozytorium nie generowała dodatkowych „tarć”. W wielu przypadkach lepsza jest prosta, ale konsekwentna struktura niż idealnie „czysta” architektura rodem z dużej firmy.
Monorepo a multirepo różnią się przede wszystkim tym, jak wyglądają codzienne operacje kontrybutorów i maintainerów.
W monorepo:
PR-y mogą dotykać kilku obszarów naraz (np. zmiany w backendzie i frontendzie, plus aktualizacja dokumentacji w jednym pull requeście);
code review jest scentralizowane – zespół przegląda zmiany w jednym miejscu, ale musi znać kontekst kilku części systemu;
wydanie (release) bywa zbiorcze – jedna wersja dla całego systemu, albo zestaw tagów i procesów w obrębie jednego repo;
CI/CD uruchamia się raz na repo (choć można go optymalizować per katalog).
W multirepo:
PR-y dotyczą zwykle jednego komponentu (np. tylko API albo tylko dokumentacji);
code review rozkłada się na różne repozytoria – łatwiej podzielić odpowiedzialność, trudniej śledzić „cały obraz” zmian;
releasy robi się osobno – każdy mikroserwis lub moduł ma własny cykl wydawniczy, czasem własny changelog;
CI/CD trzeba utrzymać osobno w każdym repo.
Jeśli projekt jest mały, a większość zmian jest przekrojowa (dotyka kilku miejsc naraz), monorepo zwykle wygrywa na wygodzie. Przy rozbudowanym ekosystemie narzędzi, integracji i pluginów multirepo może dać większą elastyczność.
Dostępność i przejrzystość dla nowych osób
Nowy wolontariusz, który trafia na stronę projektu, ma najpierw proste pytanie: gdzie jest kod i jak mogę pomóc? Od odpowiedzi na to pytanie zależy, czy zostanie na godzinę, czy na miesiące.
W monorepo:
jest jeden adres repo; trudno go przeoczyć;
łatwo przygotować jeden plik CONTRIBUTING.md opisujący zasady współpracy dla całego projektu;
nowa osoba widzi całość – od kodu po dokumentację; łatwiej znaleźć miejsce pasujące do własnych umiejętności;
ale struktura katalogów bywa przytłaczająca, jeśli rośnie bez ładu.
W multirepo:
często powstaje tzw. „repo główne” typu projekt-meta lub projekt-home, które opisuje resztę;
nowy kontrybutor musi zrozumieć, które repo jest mu potrzebne (czasem 2–3 różne do odpalenia środowiska developerskiego);
dokumentacja bywa rozproszona – kawałek w jednym repo, kawałek w innym;
za to poszczególne repo są mniejsze i łatwiejsze do ogarnięcia na raz.
W społeczności z bardzo ograniczonym czasem i dużą rotacją osób prostota onbordingu zwykle ma większą wagę niż „czystość” architektury. Stąd sporo projektów open source startuje od monorepo, a dopiero później migruje do multirepo, kiedy naprawdę pojawia się taka potrzeba.
Koszty utrzymania narzędzi i automatyzacji
Na poziomie GitHuba czy GitLaba monorepo vs multirepo to także pytanie: ile razy trzeba skonfigurować te same narzędzia. Chodzi o:
pipeline’y CI (GitHub Actions, GitLab CI, CircleCI);
szablony zgłoszeń issue i pull requestów;
boty (np. Renovate, Dependabot, Mergify);
zasady ochrony gałęzi (branch protection rules);
integracje z zewnętrznymi usługami (Slack, Discord, Sentry, itp.).
W monorepo konfigurujesz to najczęściej raz. Bywa bardziej skomplikowane (więcej warunków typu „buduj tylko gdy zmieni się folder /frontend”), ale aktualizacje robisz w jednym miejscu. W multirepo wszystko trzeba powtórzyć w każdym repo. Dla małego projektu to jeszcze do przełknięcia, ale przy pięciu–siedmiu repozytoriach zaczyna boleć, bo każda zmiana (np. migracja do nowszej wersji Node.js w CI) wymaga powielenia pracy.
Skalowanie projektu, czyli co się dzieje gdy projekt rośnie
Jeśli projekt społecznościowy się przebije i zacznie rosnąć, wybór monorepo vs multirepo zacznie bardziej ciążyć.
W monorepo podczas wzrostu pojawiają się typowe zjawiska:
kolejne katalogi z kodem, często tworzone ad hoc („dodajmy tu katalog /old-api, bo nie chcemy tego ruszać”);
CI wydłuża się, bo przy każdym PR uruchamiane są coraz liczniejsze testy;
pull requesty dotykają wielu miejsc i wymagają kilku recenzentów, co spowalnia proces;
trudniej wyodrębnić niezależne, dojrzałe moduły do osobnego cyklu życia.
W multirepo przy wzroście rośnie głównie:
liczba zależności między repo – trzeba pilnować zgodności wersji;
koszt koordynacji releasów – np. wydanie nowej wersji API wymaga osobnej aktualizacji klienta w innym repo;
liczba miejsc do ogarnięcia w CI i konfiguracjach.
Im większy projekt, tym bardziej ważne stają się zasady zarządzania modułami i pakietami oraz sposób wersjonowania – zarówno w monorepo, jak i w multirepo. Dla społeczności, która nie ma stałego full-time maintainer’a, każdy dodatkowy mechanizm to potencjalny punkt, w którym coś się „rozjedzie”.
Monorepo w projekcie społecznościowym – plusy, minusy, pułapki
Najważniejsze zalety monorepo dla społeczności
Monorepo w projekcie open source ma kilka bardzo konkretnych plusów, które mocno wspierają pracę społeczności:
wspólne standardy – jeden ESLint, jedna konfiguracja formatowania, jedna lista skryptów npm; dużo łatwiej utrzymać spójny styl kodu;
łatwiejsze refaktoryzacje „przez cały projekt” – zmiana nazwy endpointu w API i dostosowanie frontendu robione są w jednym miejscu, jednym PR-em;
jedna konfiguracja CI/CD – nawet jeśli jest rozbudowana, utrzymuje się ją w jednym repozytorium;
spójne wersje zależności – widać w jednym package.json (lub w kilku w obrębie workspace’ów), z czego korzysta cały projekt.
Dla nowych kontrybutorów monorepo to również:
jedno miejsce do śledzenia issue – nie trzeba przeskakiwać między trzema repo;
prostsze forki – klonuje się jedno repo i ma się pod ręką całość kodu;
jednolity proces pull requestów – ten sam plik CONTRIBUTING, te same zasady commitów i recenzji.
Jeśli społeczność ma ograniczony czas i nie stać jej na utrzymywanie złożonych narzędzi do zarządzania ekosystemem wielu repozytoriów, monorepo bardzo często jest rozsądniejszym, tańszym rozwiązaniem na kilka pierwszych lat życia projektu.
Ułatwienia dla nowych kontrybutorów w monorepo
Dla osoby, która chcę pomóc, ale niekoniecznie jest doświadczonym inżynierem, kluczowe są:
klarowna struktura katalogów;
czytelne opisy zadań (issue);
niewielka liczba kroków, aby uruchomić środowisko lokalne.
Monorepo daje możliwość ustawienia tego wszystkiego centralnie. Przykładowy minimalny schemat:
/frontend – README.md z instrukcją „jak uruchomić UI”;
/backend – README.md z opisem API i komendami do odpalenia serwera;
/docs – opis funkcjonalny projektu dla osób nietechnicznych;
CONTRIBUTING.md – krok po kroku jak przygotować pierwszy PR.
Nowa osoba nie musi zgadywać, który z trzech repo jest „tym właściwym”. Wchodzi w jeden projekt, a struktura katalogów i dokumentacja kierują ją dalej. To bardzo zmniejsza próg wejścia i liczbę pytań w stylu „gdzie mam zgłosić błąd?” lub „które repo mam zforkować?”.
Główne wady monorepo z perspektywy społeczności
Monorepo ma jednak swoje poważne minusy, które wyłażą na wierzch szczególnie wtedy, gdy projekt zaczyna być popularny:
Monorepo jako źródło tarcia i konfliktów
Im większa różnorodność osób i technologii w projekcie, tym bardziej monorepo potrafi stać się miejscem nieporozumień. Nie chodzi tylko o technikalia, ale też o „politykę” w kodzie.
Konflikty interesów między zespołami – frontend chce szybkich releasów i lekkich procesów, backend woli spokojniejszy rytm i twardsze zasady jakości. W monorepo te dwie filozofie zderzają się w jednym miejscu, w jednym CI i jednym procesie review.
Większa liczba recenzentów na jeden PR – jeśli zmiany dotykają kilku modułów, recenzentów przybywa. W projekcie społecznościowym, gdzie wszyscy robią review po pracy, czas oczekiwania na akceptację łatwo rozciąga się z dni do tygodni.
Słabsze poczucie „własności” kodu – gdy „wszyscy są odpowiedzialni za wszystko”, w praktyce nikt nie czuje się naprawdę odpowiedzialny za żaden wycinek. Zgłoszenia wiszą, bo każdy liczy, że ktoś inny się tym zajmie.
Przy małej aktywnej grupie łatwo rozwiązać to kilkoma prostymi zasadami, ale im więcej osób dołącza, tym częściej dyskusje o strukturze repo czy zasadach CI zabierają czas, który mógłby pójść na rozwój funkcji.
Problemy techniczne typowe dla monorepo
Techniczne minusy monorepo zwykle wychodzą w najmniej wygodnym momencie – np. podczas hackathonu, gdy wszyscy na raz robią PR-y.
Rosnący czas CI – nawet jeśli starasz się uruchamiać testy selektywnie, przy słabiej ustawionych regułach łatwo dojść do sytuacji, w której drobna zmiana w dokumentacji budzi pełny pipeline. Gdy kolejka PR-ów jest długa, to zabija tempo.
Konflikty merge’ów w plikach konfiguracyjnych – wspólne pliki typu package.json, yarn.lock, docker-compose.yml czy centralne konfiguracje CI stają się gorącym punktem konfliktów. Dla mniej doświadczonych osób rozwiązywanie takich konfliktów to często ściana.
Problemy z wydzieleniem stabilnych modułów – kiedy jakaś część projektu dojrzewa i wypadałoby ją ustabilizować (np. wspólną bibliotekę komponentów), ciasne powiązania wewnątrz monorepo utrudniają nadanie jej osobnego rytmu wersjonowania.
Ciężkie klony i check-outy – przy długiej historii i dużej ilości artefaktów binarnych w repo (złe praktyki, ale w społecznościach się zdarzają) klonowanie monorepo może słabym łączom zająć absurdalnie długo.
Jak ograniczać minusy monorepo przy minimalnym wysiłku
Zamiast inwestować w drogie narzędzia, w projekcie społecznościowym lepiej skupić się na kilku niedrogich nawykach, które mocno łagodzą problemy monorepo.
Proste reguły podziału katalogów – np. „każdy większy komponent ma własny folder z README.md i osobnym package.json / modułem”. To nie wymaga żadnych narzędzi, a już porządkuje przestrzeń.
Minimalny, ale jasny ownership – plik CODESOWNERS lub nawet zwykła tabela w CONTRIBUTING.md z przypisaniem obszarów do osób/nicków. Recenzje nie wiszą w próżni, bo każdy wie, kogo zawołać.
Selektywne uruchamianie CI – nawet proste warunki oparte o ścieżki (np. w GitHub Actions: paths / paths-ignore) sprawiają, że dokumentacja nie przepala pełnego pipeline’u backendu.
Stałe sprzątanie „starych” rzeczy – zamiast trzymać w monorepo nieużywany katalog /old-api przez lata, lepiej przenieść go do archiwalnego repo lub oznaczonego forka. Mniej kodu to mniej zamieszania.
Multirepo w projekcie społecznościowym – plusy, minusy, pułapki
Kiedy multirepo ma naturalny sens
Multirepo zaczyna wygrywać, gdy projekt bardziej przypomina ekosystem niż jedną aplikację i gdy za różne fragmenty odpowiadają różne grupy ludzi.
Wyraźnie odseparowane domeny – np. jedno repo na aplikację mobilną, inne na backend API, kolejne na stronę WWW. Z góry wiadomo, że te części mogą rozwijać się w różnym tempie.
Osobne cykle życia – biblioteka SDK używana w kilku projektach, paczki npm, pluginy do popularnych narzędzi. Utrzymywanie tego w jednym monorepo wymusza wspólne release’y, co bywa sztuczne.
Partnerzy zewnętrzni – jeśli np. zewnętrzny zespół ma rozwijać tylko aplikację mobilną, dużo łatwiej przekazać im jedno repo niż wprowadzać ich w skomplikowany monorepo z całą infrastrukturą.
W praktyce multirepo często pojawia się jako efekt uboczny: ktoś wyciąga jedną część systemu do osobnego repo, żeby szybciej działać lub uniknąć konfliktów w głównym projekcie.
Najważniejsze zalety multirepo z perspektywy społeczności
Główne argumenty „za” multirepo to porządek organizacyjny i większa swoboda w sposobie pracy poszczególnych zespołów.
Mniejsze, łatwiejsze do ogarnięcia repozytoria – nowa osoba, która chce pomóc tylko przy dokumentacji lub tylko przy front-endzie, nie musi pobierać i rozumieć całego ekosystemu.
Własne zasady dla każdego repo – inny linter, inne zasady review, osobne cykle wydań. To szczególnie pomaga, gdy części projektu korzystają z różnych technologii (np. Python/Go/JS).
Mocniejsze poczucie odpowiedzialności – zespół opiekujący się jednym repo zwykle traktuje je jak własny ogródek. Łatwiej też mierzyć i komunikować, które repo jest „aktywnie utrzymywane”, a które jest w trybie „maintenance only”.
Izolacja długów technicznych – problemy z jednym repo (np. przestarzałe zależności) nie blokują innych. Można zaplanować ich spłatę w spokojniejszym czasie, nie zamrażając całego projektu.
Kluczowe wady i koszty multirepo
Za tę elastyczność trzeba jednak zapłacić – głównie czasem osób, które i tak mają go mało.
Współzależności wersji – jeśli backend jest w wersji 1.4, a frontend działa poprawnie tylko z 1.3, utrzymanie zgodności staje się codziennym zadaniem. Bez porządnej dokumentacji wersji i zmian kończy się to zgadywaniem „co z czym działa”.
Rozproszone zgłoszenia błędów – jeden błąd użytkownika może dotyczyć kilku repo (np. API i klienta). Przy braku dobrego repo „meta” issue lądują losowo, a ktoś musi je ręcznie przekierowywać.
Powielony wysiłek w konfiguracji – każde repo wymaga osobnej konfiguracji CI, szablonów issue, Dependabota, ustawień branch protection. Dla dwóch repo to jeszcze nic, dla siedmiu robi się z tego cała lista zadań administracyjnych.
Dodatkowe bariery dla nowych osób – nowy kontrybutor musi najpierw zrozumieć, który fragment go interesuje i jakie repo są ze sobą powiązane, zanim w ogóle cokolwiek uruchomi.
Typowe pułapki multirepo w społecznościach
W miarę jak rośnie liczba repozytoriów, pojawiają się powtarzalne problemy organizacyjne.
„Sierotki” repo – małe, kiedyś stworzone repozytoria (np. jednorazowy skrypt, stara wersja narzędzia), do których nikt się nie przyznaje. Mają stare zależności i braki w dokumentacji, ale nadal są widoczne w organizacji i budzą wątpliwości, czy można ich używać.
Brak wspólnego miejsca na decyzje – ustalenia architektoniczne albo standardy kodu lądują przypadkowo w jednym z repo. Inni o nich nie wiedzą, więc powstają rozbieżne rozwiązania.
Fragmentacja społeczności – część osób zna się tylko w kontekście „swojego” repo i rzadko zagląda do innych. W efekcie współpraca między komponentami bywa słaba, bo każdy myśli kategoriami swojego wycinka.
Jak używać multirepo „po taniości”
Da się ograniczyć koszty multirepo bez rozbudowanych narzędzi klasy enterprise. Sprawdza się kilka prostych trików.
Jedno repo „meta” jako centrum dowodzenia – zwięzły opis całego ekosystemu, lista repo z linkami, podstawowe zasady, roadmapa, ogłoszenia. To może być zwykłe repo z README.md i kilkoma dokumentami, ale staje się pierwszym miejscem, do którego kierujesz nowych ludzi.
Wspólne szablony przez „template repo” – jedno repo wzorcowe z .github, podstawowym CI i przykładową strukturą. Nowe repozytoria tworzy się jako „Use this template”. To jednorazowa inwestycja, która zwraca się przy każdym kolejnym projekcie.
Proste oznaczenia wersji zgodnych ze sobą – nawet tabelka w dokumentacji typu „frontend 2.x działa z backend 1.4+” usuwa część zgadywania. Nie trzeba od razu wchodzić w skomplikowane systemy zarządzania wersjami.
Minimalna automatyzacja cross-repo – np. workflow w GitHub Actions, który przy wydaniu nowej wersji API automatycznie otwiera issue w repo klienta z informacją „pojawiła się wersja X, trzeba zaktualizować zależności”. To mała automatyzacja, a oszczędza sporo pamiętania.
Źródło: Pexels | Autor: Christina Morillo
Jak ocenić, które podejście pasuje do konkretnego projektu społecznościowego
Kluczowe pytania na start
Zamiast zaczynać od „co jest modne”, lepiej zadać kilka prostych pytań o realia projektu.
Ile macie realnie czasu miesięcznie na utrzymanie infrastruktury? Jeśli odpowiedź brzmi „kilka godzin po pracy”, monorepo z prostą konfiguracją jest zwykle bezpieczniejszym wyborem.
Jak bardzo różne są technologie w projekcie? Jeden stos technologiczny (np. Node.js + React) sprzyja monorepo. Mieszanka Go, Pythona, JS i aplikacji mobilnych – raczej skłania ku przynajmniej częściowemu multirepo.
Jak często zmiany dotykają wielu komponentów naraz? Jeśli większość prac to „przekrojowe” zadania (API + frontend + dokumentacja), monorepo upraszcza życie. Gdy typowe są niezależne moduły, multirepo bywa wygodniejsze.
Jak duża jest rotacja wolontariuszy? Przy dużej rotacji liczy się minimalny próg wejścia, czyli jeden adres repo, jedno CONTRIBUTING.md, jedno miejsce z issue.
Prosty schemat decyzyjny „na chłopski rozum”
Można ułożyć sobie bardzo uproszczony algorytm wyboru, bez nadmiernej teorii.
Czy projekt ma mniej niż 3 główne komponenty? (np. frontend, backend, dokumentacja)
Jeżeli tak, zacznij od monorepo. Rozbijesz je później, jeśli będzie trzeba.
Czy istnieje przynajmniej jeden komponent, który ma być używany niezależnie? (np. SDK, biblioteka, plugin)
Jeśli tak, rozważ trzymanie tylko tego komponentu w osobnym repo, resztę zostawiając w monorepo. To kompromis.
Czy ktokolwiek w zespole ma doświadczenie w utrzymywaniu multirepo?
Jeśli nie, najtańszą opcją jest monorepo plus ewentualne wydzielenie dopiero wtedy, gdy ktoś z praktyką dołączy.
Czy planujesz aktywnie współpracować z zewnętrznymi zespołami?
Jeśli tak, od razu zaplanuj przynajmniej jedno oddzielne repo dla fragmentów, które będą rozwijane na zewnątrz (np. aplikacja mobilna tworzona przez partnera).
Scenariusz „monorepo na start, multirepo później”
W praktyce rozsądne, budżetowe podejście wygląda często tak: zaczynasz od monorepo, ale projektujesz je tak, jakby pewne części miały kiedyś trafić do osobnych repozytoriów.
Wyraźne oddzielenie komponentów folderami – struktura typu /apps/frontend, /apps/backend, /packages/shared ułatwia późniejsze „wycięcie” całego katalogu do nowego repo.
Publiczne interfejsy zamiast „skrótów” – zamiast korzystać z wewnętrznych plików innych modułów, definiujesz oficjalne API (np. eksporty z index.ts). Gdy przyjdzie czas na migrację do osobnego repo, liczba zależności do naprawienia spada.
Osobne README dla kluczowych folderów – w momencie wydzielania repo można je niemal skopiować i masz gotową podstawę dokumentacji w nowym miejscu.
Takie podejście nie wymaga drogiej infrastruktury ani złożonej orkiestracji, a jednak zostawia furtkę na skalowanie w przyszłości.
Kiedy nie ma sensu na siłę rozbijać monorepo
Rozbicie na multirepo ma sens tylko wtedy, gdy realnie obniża koszty, a nie dlatego, że „poważne projekty tak robią”. Są sytuacje, w których lepiej zostać przy jednym repo.
Przykłady sytuacji, w których monorepo wciąż wygrywa
Do jednego repozytorium opłaca się trzymać się kurczowo częściej, niż się wydaje. Kilka typowych sytuacji wygląda podobnie.
Jedno środowisko uruchomieniowe, wiele małych usług – kilka serwisów Node.js, parę workerów, panel administracyjny. Technicznie można je porozdzielać, ale całość utrzymują te same 2–3 osoby po godzinach. Jeden pipeline CI i jedna konfiguracja lintera bywają wtedy na wagę złota.
Projekt edukacyjny lub mentoringowy – jeśli główny cel to uczenie nowych osób, jeden adres repo i jedno README wygrywa z elegancką architekturą rozbitą na pięć miejsc. Porządek w kodzie jest ważny, ale jeszcze ważniejsza jest niski próg wejścia.
Brak stabilnego „trzonu” zespołu – kiedy rotacja wolontariuszy jest wysoka, a nikt nie pełni faktycznej roli „maintainera infrastruktury”, lepiej uprościć życie następnym niż projektować wielopoziomowe struktury.
Dominują zmiany przekrojowe – jeśli większość tasków dotyczy kilku warstw naraz (np. „dodaj nowy typ zgłoszenia” = migracja bazy + API + UI), monorepo zmniejsza tarcie między zespołami i pozwala zamknąć całość jednym PR-em.
Sygnalizatory, że czas jednak wydzielić osobne repo
Nie trzeba robić formalnych audytów, żeby wychwycić moment, kiedy monorepo zaczyna przeszkadzać bardziej niż pomaga. Kilka prostych objawów mówi sporo.
Stale blokujące się PR-y – zmiana w jednym katalogu czeka, bo testy w innym module wiecznie się wywalają. Jeżeli duża część czasu review to „odpal jeszcze raz cały pipeline, bo coś padło bokiem”, to sygnał, że zakres jednego repo jest za duży.
Różne rytmy wydawnicze – gdy jedna część projektu wymaga releasów kilka razy w tygodniu, a inna raz na kwartał, wspólny cykl wydań zaczyna być kulą u nogi dla obu.
Trwałe różnice technologiczne – jeśli w obrębie jednego repo jedna aplikacja pracuje na bardzo nowym stacku, a inna na starym, i te światy rzadko się dotykają, utrzymywanie wspólnych narzędzi staje się coraz trudniejsze.
Osobne grupy opiekunów – gdy naturalnie tworzą się „podzespoły”, które prawie nie recenzują sobie nawzajem kodu, tylko zajmują się jednym katalogiem, oddzielne repo często porządkuje odpowiedzialności zamiast je komplikować.
Koszt czasu i pieniędzy – pragmatyczne spojrzenie na monorepo i multirepo
Jak liczyć koszty, gdy większość pracuje „po godzinach”
W projektach społecznościowych „budżet” to najczęściej nie przelew z grantów, tylko kilkadziesiąt godzin wolnego czasu miesięcznie. Decyzja o strukturze repo to w praktyce decyzja, na co ten czas pójdzie.
Koszt konfiguracji początkowej – ile realnie wieczorów potrzebujesz, by postawić CI, linting, testy i podstawowe szablony issue? W monorepo robisz to raz, w multirepo razy „n”. To szczególnie bola, gdy konfiguracja jest nietrywialna (np. kilka środowisk deployu).
Koszt bieżącego administrowania – uprawnienia, brancha głównego, zasady review, integracje (Slack, Matrix, Discord) – to wszystko trzeba utrzymywać. W jednym repo przestawiasz kilka suwaków, w wielu repo robi się z tego mały projekt.
Koszt poznawczy dla nowych osób – 30 minut więcej na zrozumienie struktury to niby nic, ale jeśli większość wolontariuszy robi pojedynczy mały wkład, ta bariera przekłada się bezpośrednio na liczbę PR-ów.
Koszt błędów w wersjach – w multirepo do budżetu czasu trzeba doliczyć „gaszenie pożarów”, gdy coś nie zadziała, bo ktoś użył nie tej wersji serwisu czy biblioteki.
Co jest „drogie”, a co „tanie” w utrzymaniu monorepo
Jedno repo jest tanie w konfiguracji, ale potrafi być kosztowne w utrzymaniu, jeśli przesadzimy z ambicjami. Kilka obszarów bywa szczególnie pracożernych.
Rozbudowane pipeline’y CI – testy E2E, konteneryzacja, preview deployments. Dają świetne efekty, ale każdy dodatkowy krok to potencjalny punkt awarii. Dla małego projektu często wystarczy zestaw „lint + testy jednostkowe + proste buildy”.
Agresywne reguły review – wymaganie 2–3 reviewerów do każdego PR-a brzmi profesjonalnie, ale przy małym zespole zamraża rozwój. Dla części katalogów można świadomie przyjąć lżejsze zasady, a surowsze zostawić tylko w najważniejszych.
Skrajnie skomplikowane narzędzia do monorepo – Nx, Bazel czy zaawansowane orkiestratory są potężne, ale czas potrzebny, by je wdrożyć i utrzymać, często przerasta zyski w małym projekcie.
Tanie podejście do monorepo to raczej prosty zestaw narzędzi (np. podstawowe GitHub Actions, jeden menedżer pakietów) niż pełne odwzorowanie rozwiązań dużych firm.
Gdzie multirepo naprawdę „zjada” budżet
Rozbicie projektu na wiele repozytoriów ma sens, ale opłaca się tylko wtedy, gdy koszty są pod kontrolą. Największe „pożeracze czasu” zwykle nie są oczywiste na początku.
Duplikacja konfiguracji – każde kolejne repo to kolejny plik .github/workflows, kolejne reguły branch protection, kolejne szablony issue i PR. Bez automatyzacji lub dobrego template’u administrowanie tym pochłania godziny.
Koordynacja wydań – kiedy zmiana w bibliotece wymaga kolejnych wydań klienta i serwera, a każdy z nich ma osobny pipeline, nagle trzeba żonglować tagami, changelogami i synchronizacją zespołów.
Rozbieżne praktyki – różne repo zaczynają żyć własnym życiem: inne style commitów, inne standardy kodu, inne zasady review. Potem ktoś musi spędzić sporo czasu na „porządkach” i unifikacji.
Tani sposób na ograniczenie kosztów multirepo
Zamiast inwestować w ciężkie rozwiązania typu self-hosted GitLab z rozbudowaną orkiestracją, można podejść do sprawy minimalistycznie.
Jedno „szablonowe” repo z infrastrukturą – trzymasz tam .github, podstawowe workflow, CONTRIBUTING.md, CODE_OF_CONDUCT.md, licencję. Nowe repozytoria tworzysz już z tym zestawem, więc konfiguracja nie rozjeżdża się na starcie.
Skrypty do hurtowej konfiguracji – nawet prosty skrypt bash + GitHub CLI, który ustawia domyślne reguły na nowych repo (np. wyłącza direct push na main, włącza wymaganie review), zdejmuje z barków sporo powtarzalnej pracy.
Jeden prosty standard commitów i wydań – ustalenie, że używacie np. SemVer i prostego konwencjonalnego formatowania commitów („feat: …”, „fix: …”) we wszystkich repo, pomaga automatyzować changelogi i oznaczanie wersji bez skomplikowanych narzędzi.
Prosty monorepo dla projektów społecznościowych – jak to ugryźć krok po kroku
Minimalna struktura katalogów na początek
Zamiast projektować idealny układ katalogów na pięć lat do przodu, lepiej postawić na prosty, ale przyszłościowy schemat. Taki, który nie przeszkadza, a w razie potrzeby pozwoli łatwo coś wydzielić.
To wystarcza, żeby nowa osoba od razu wiedziała, gdzie szukać frontendu, backendu i rzeczy wspólnych. A jeśli kiedyś apps/web czy packages/shared staną się „za duże”, można po prostu przenieść cały katalog do osobnego repo.
Jedno środowisko deweloperskie „dla ludzi”
Duża część frustracji w projektach społecznościowych bierze się z trudnego startu. Naturalnym celem powinien być jeden prosty sposób na uruchomienie projektu lokalnie.
Jeden skrypt startowy – np. make dev albo npm run dev, który pod spodem uruchamia zarówno frontend, jak i backend. W dokumentacji opisujesz tylko ten skrypt, a nie pełny zestaw poleceń.
Prosty opis zależności – na początku wystarczy wypisać w README, że potrzebne są np. Node, Docker i make. Instalacja wszystkiego „za usera” brzmi atrakcyjnie, ale zajmuje zbyt dużo czasu utrzymaniowego.
Domyślne dane demo – skrypt, który zasiewa lokalną bazę testowymi danymi. Nowe osoby mogą wejść do działającej aplikacji, zamiast walczyć z pustymi ekranami.
Najprostsze możliwe CI dla monorepo
Zestaw pipeline’ów da się zaprojektować tak, żeby był bardziej sprzymierzeńcem niż źródłem frustracji. Punktem wyjścia może być wariant „tylko to, co naprawdę blokuje błędy”.
Oddzielne joby per katalog – prosty workflow, który na podstawie zmienionych plików odpala testy tylko dla apps/web albo tylko dla apps/api. W GitHub Actions można to zrobić prostymi warunkami paths.
Jeden job „lint + testy jednostkowe” – bez fajerwerków typu matrix na kilkanaście wersji środowiska. W miarę jak projekt rośnie, można dodawać więcej wariantów.
Build produkcyjny tylko na main – pełny build (i ewentualny deploy) uruchamiasz jedynie dla gałęzi głównej i tagów wydań. Dzięki temu PR-y nie czekają w kolejce do „ciężkiego” pipeline’u.
Konwencje i automatyzmy, które naprawdę pomagają
Zachęcające jest wdrażanie dziesiątek reguł jakości, ale największy zwrot z inwestycji dają kilka prostych, dobrze dogadanych zasad.
Spójne nazwy katalogów i pakietów – nazwy apps/web, apps/api, packages/shared mówią same za siebie. Unika się kreatywnych, ale niejasnych nazw typu phoenix, hydra itp.
Szablon PR z checklistą – krótka lista typu „[ ] dodałem testy”, „[ ] zaktualizowałem dokumentację jeśli trzeba”, „[ ] uruchomiłem lokalnie npm test” przypomina o podstawach bez dodatkowych spotkań.
Automatyczne formatowanie – narzędzia typu Prettier lub black uruchamiane lokalnie (np. przez git hook albo skrypt format) zmniejszają liczbę jałowych dyskusji o stylu.
Narzędzia typu Turborepo, Nx czy pnpm workspaces potrafią mocno przyspieszyć pracę w monorepo, ale nie muszą być włączone od pierwszego commita. Zdrowsza ścieżka rozwoju wygląda często tak:
Faza 1: ręczne skrypty – proste komendy w package.json czy Makefile, uruchamiane ręcznie lub przez CI. Celem jest „żeby działało”.
Faza 2: wspólny menedżer pakietów – przejście na workspaces w npm/yarn/pnpm, gdy pojawi się więcej współdzielonych modułów. To głównie porządek w zależnościach, a nie rewolucja procesowa.
Faza 3: narzędzie do orkiestracji – dopiero gdy czas buildów i testów zacznie realnie przeszkadzać, włącza się coś, co ogarnia cache i zależności między pakietami. Na tym etapie łatwiej zaakceptować koszt nauki narzędzia.
Przykładowy „plan dnia” dla osoby ogarniającej monorepo
Przy małym projekcie zwykle jest jedna osoba, która z grubsza dba o „techniczną higienę” repozytorium. Żeby nie zamieniło się to w drugi etat, można przyjąć lekką rutynę.
Raz w tygodniu – przegląd otwartych PR-ów, szybkie poprawki w CI, zamknięcie przestarzałych issue, które blokują innych.
Raz w miesiącu – aktualizacja kluczowych zależności (np. frameworków), przegląd struktury katalogów (czy coś nie urosło na tyle, że zasługuje na wydzielenie do packages albo osobnego modułu).
Raz na kwartał – krótka sesja „porządkowa”: uproszczenie zbyt skomplikowanych workflow, usunięcie martwych skryptów, dopisanie brakujących fragmentów dokumentacji.
Co przygotować, zanim monorepo zacznie się „rozsypywać”
