Jak zorganizować projekt w repozytorium – kompletny przewodnik po strukturze
Pytanie o to, jak zorganizować projekt w repozytorium, wraca w każdym zespole, który przekroczył próg trzech programistów i dwóch środowisk uruchomieniowych. Odpowiedź na to, jak zorganizować projekt w repozytorium, rzadko sprowadza się do jednego uniwersalnego szablonu katalogów — decyduje spójność konwencji, czytelność historii commitów oraz to, czy nowa osoba w zespole jest w stanie uruchomić aplikację lokalnie w trzydzieści minut. Repozytorium przestało być wyłącznie miejscem na kod źródłowy: trzyma się w nim definicje infrastruktury, pliki konfiguracyjne serwera, skrypty migracji bazy danych, dokumentację wdrożeniową i szablony pipeline’ów CI/CD. Źle poukładany katalog główny z czterdziestoma plikami na jednym poziomie kosztuje realne godziny — w większych organizacjach szacuje się to na kilkanaście procent czasu deweloperów przeznaczonego na samo szukanie właściwego pliku. Dobra struktura jest natomiast tania: kilka godzin pracy na starcie i konsekwentne trzymanie się ustalonych reguł przez cały cykl życia produktu.
Katalog główny jako wizytówka projektu
Katalog główny to pierwsze, co widzi każdy odwiedzający repozytorium — recenzent, audytor bezpieczeństwa i kandydat na nowego członka zespołu. Jeśli znajduje tam czterdzieści pozycji bez wyraźnego porządku, wrażenie jest jednoznaczne: projekt rósł chaotycznie. Zdrowy root ma zwykle od ośmiu do piętnastu wpisów i każdy z nich da się uzasadnić jednym zdaniem.
Podstawowa zasada brzmi: root zawiera manifesty i metadane, a nie kod domenowy. Pliki takie jak package.json, composer.json, pyproject.toml, Makefile czy docker-compose.yml opisują projekt jako całość. Wszystko, co należy do jednej funkcjonalności, schodzi piętro niżej — do src, app, packages albo services, zależnie od przyjętej w zespole konwencji nazewniczej.
Druga zasada dotyczy plików tymczasowych. Katalogi node_modules, vendor, .venv, dist czy build nigdy nie trafiają do historii — od tego jest .gitignore, przygotowany zanim padnie pierwszy commit. Repozytorium ważące 900 MB przez przypadkowo dodane paczki i zrzuty bazy spowalnia klonowanie oraz każdy przebieg pipeline’u, a w płatnych planach CI przekłada się to wprost na rachunek.
Minimalny zestaw plików w katalogu głównym
| Element | Rola w repozytorium |
|---|---|
| README.md | Opis projektu, wymagania wstępne i instrukcja uruchomienia w kilku krokach |
| .gitignore | Lista artefaktów budowania i plików lokalnych wykluczonych z historii |
| .env.example | Szablon zmiennych środowiskowych bez żadnych realnych haseł ani kluczy |
| CONTRIBUTING.md | Konwencja gałęzi, commitów i zasady zgłaszania pull requestów |
| docker-compose.yml | Powtarzalne środowisko lokalne z bazą danych, cache i kolejką |
Taki zestaw sprawdza się zarówno w monolicie w PHP, jak i w projekcie mikroserwisowym w Go. Jeśli technologia wymaga dodatkowych manifestów, dopisuje się je pojedynczo i świadomie, zamiast dokładać kolejne pliki konfiguracyjne przy każdym eksperymencie z nowym narzędziem, o którym nikt po miesiącu nie pamięta.
Konwencje nazewnictwa i podział na moduły
Nazewnictwo jest tańszą formą dokumentacji niż komentarze. Wybierz jedną konwencję dla katalogów — kebab-case albo snake_case — i trzymaj się jej w całym drzewie. Mieszanka user-profile, UserProfile i user_profile w sąsiadujących folderach generuje konflikty na systemach plików rozróżniających wielkość liter, zwłaszcza między macOS a Linuksem na serwerze docelowym.
Podział na moduły warto prowadzić według domeny biznesowej, a nie według typu pliku. Struktura z katalogami controllers, models i views wygląda schludnie przy dziesięciu klasach i staje się nieczytelna przy dwustu. Układ modules/platnosci, modules/zamowienia, modules/uzytkownicy trzyma powiązany kod obok siebie i wyraźnie skraca czas nawigacji po projekcie.
Każdy moduł powinien mieć jasno wyznaczoną granicę: publiczne API w jednym pliku wejściowym i resztę traktowaną jako implementacja wewnętrzna. Gdy moduł zaczyna importować dziesięć plików z sąsiada, to czytelny sygnał, że granica została naruszona i albo wymaga korekty, albo oba moduły powinny się po prostu połączyć.
Gałęzie, commity i czytelna historia zmian
Historia commitów jest dziennikiem śledczym projektu. Pytanie o to, jak zorganizować projekt w repozytorium, obejmuje również to, jak wyglądają gałęzie: krótkie, jednozadaniowe, nazwane według wzorca typ/numer-zgloszenia-krotki-opis, na przykład feat/1423-koszyk-kupony. Gałąź żyjąca trzy tygodnie prawie zawsze kończy się bolesnym i ryzykownym scaleniem.
Gałąź główna musi być zawsze gotowa do wdrożenia. Oznacza to ochronę przed bezpośrednim pushem, wymóg przeglądu kodu i zielony pipeline jako warunek scalenia. Te trzy reguły ustawia się w interfejsie hostingu repozytoriów w kilka minut, a eliminują one większość incydentów typu ktoś wysłał zmianę prosto na produkcję.
Tagi i wersjonowanie semantyczne porządkują wydania. Format MAJOR.MINOR.PATCH mówi wprost, czy aktualizacja wymaga zmian po stronie klienta. Do tego plik CHANGELOG.md generowany z komunikatów commitów daje działowi wsparcia konkretną odpowiedź na pytanie, co dokładnie zmieniło się między wersjami 2.4.1 a 2.5.0.
Komunikaty commitów, które skracają debugowanie
Konwencja Conventional Commits — feat, fix, docs, refactor, chore, z opcjonalnym zakresem w nawiasie — kosztuje sekundę przy pisaniu i zwraca się przy pierwszym poszukiwaniu regresji. Komunikat fix(platnosci): poprawka zaokrąglenia przy rabacie procentowym niesie informację, której lakoniczne poprawki czy update nigdy nie przekażą recenzentowi.
Jeden commit powinien odpowiadać jednej logicznej zmianie. Rozdzielenie refaktoryzacji od zmiany zachowania sprawia, że przegląd kodu trwa dziesięć minut zamiast godziny, a narzędzie bisect faktycznie wskazuje winowajcę, zamiast zwracać jeden ogromny commit zmieniający sto plików naraz i niczego nie tłumaczący.
Konfiguracja środowisk i infrastruktura w repozytorium
Repozytorium powinno opisywać nie tylko aplikację, ale i środowisko, w którym ona żyje. Decyzja o tym, jak wybrać hosting pod WordPress albo pod aplikację w Node.js, zapada raz, a jej konsekwencje — limity pamięci, wersja PHP, dostęp do CLI, obecność crona — wracają przy każdym kolejnym wdrożeniu i każdej rekrutacji.
Ten sam plik dokumentacji jest właściwym miejscem na wyjaśnienie, czym różni się VPS od hostingu współdzielonego w kontekście konkretnego projektu. Współdzielony pakiet za 15–30 zł miesięcznie wystarczy blogowi firmowemu, ale nie obsłuży kolejki zadań ani własnego procesu Node. VPS od około 25 zł wzwyż daje uprawnienia root, a więc również obowiązek aktualizacji.
Do repozytorium warto wciągnąć także konfigurację warstwy sieciowej. Instrukcja opisująca, jak skonfigurować rekordy DNS domeny, krótka notatka tłumacząca, co to jest rekord CNAME i dlaczego wskazuje on na nazwę zamiast na adres IP, oraz gotowy fragment pokazujący, jak ustawić przekierowanie 301 w htaccess, oszczędzają godziny zgadywania podczas awarii.
Osobny runbook przydaje się przy zmianie dostawcy. Procedura opisująca, jak przenieść stronę na inny hosting, jak zainstalować certyfikat SSL na serwerze docelowym i skąd wziąć darmowy certyfikat SSL Let’s Encrypt, zamienia stresującą noc migracji w listę odhaczanych kroków. Dopisz też, jak sprawdzić, kto jest właścicielem domeny, oraz jak przedłużyć domenę po wygaśnięciu.
- szablony rekordów DNS dla środowiska produkcyjnego i testowego,
- plik .htaccess z komplem reguł przekierowań i wymuszeniem HTTPS,
- skrypt automatycznie odnawiający certyfikat wraz z wpisem w cronie,
- runbook migracji między dostawcami z listą kontrolną,
- rejestr domen z datami wygaśnięcia i przypisanym właścicielem.
Dokumentacja i onboarding, czyli README, które ktoś przeczyta
README decyduje o tym, czy nowa osoba zacznie pracę tego samego dnia. Kolejność jest sprawdzona: jednozdaniowy opis produktu, wymagania wstępne z konkretnymi wersjami, blok poleceń instalacyjnych do skopiowania, sposób uruchomienia testów i krótka mapa katalogów. Wszystko, co da się zautomatyzować skryptem, powinno być skryptem, a nie akapitem.
Automatyzacja bramek jakości jest naturalnym przedłużeniem dobrej struktury. Linter, formatter i testy jednostkowe uruchamiane w hooku pre-commit oraz powtórzone w pipeline usuwają z przeglądów kodu dyskusje o wcięciach i pozwalają recenzentom skupić uwagę na logice biznesowej zamiast na stylu zapisu i szerokości tabulatora.
W dokumentacji dla zespołów rozproszonych zmieści się też akapit czysto praktyczny: jak sprawdzić prędkość internetu rzetelnie — pomiarem po kablu, o różnych porach dnia, bez włączonego VPN — oraz jak wzmocnić sygnał WiFi w domu, bo zerwane połączenie w trakcie wysyłania dużej gałęzi to problem powtarzalny i kosztowny czasowo.
Dokumentacja starzeje się szybciej niż kod, więc przypisz ją do konkretnego właściciela i przeglądaj co kwartał. Prosty test skuteczności: poproś nową osobę, żeby postawiła projekt wyłącznie na podstawie README, i notuj każde miejsce, w którym musiała zapytać kogoś na czacie. Te miejsca są gotową listą zadań.
Jak zorganizować projekt w repozytorium, gdy pracuje nad nim jedna osoba?
Zasady nie zmieniają się drastycznie, zmienia się jedynie ich rygor. Nawet w projekcie jednoosobowym opłaca się utrzymać czytelny katalog główny, plik .gitignore przygotowany przed pierwszym commitem, README z instrukcją uruchomienia i .env.example zamiast realnych haseł zapisanych w historii. Rezygnacja z rozbudowanego modelu gałęzi jest w pełni uzasadniona — praca na gałęzi głównej z krótkimi gałęziami funkcyjnymi zwykle wystarcza. Zachowaj natomiast konwencję commitów, ponieważ po pół roku samodzielny autor jest dla siebie obcą osobą, a czytelna historia skutecznie zastępuje pamięć. Największą różnicą jest brak recenzenta, więc rolę bramki jakości przejmują automaty: testy, linter i pipeline uruchamiany przy każdym pushu.
Czy monorepo sprawdzi się lepiej niż osobne repozytoria dla każdej usługi?
To zależy głównie od tego, jak często zmiany przecinają granice usług. Monorepo wygrywa, gdy jedna funkcjonalność wymaga równoczesnej modyfikacji backendu, frontendu i wspólnej biblioteki typów — wtedy jeden pull request opisuje całość, a refaktoryzacja wspólnego kodu odbywa się atomowo. Ceną jest wolniejszy pipeline i konieczność wdrożenia narzędzi budujących wyłącznie zmienione pakiety. Osobne repozytoria sprawdzają się przy niezależnych zespołach, różnych cyklach wydawniczych i odmiennych wymaganiach dotyczących uprawnień. Praktyczna wskazówka: zespoły do mniej więcej dwudziestu osób zwykle zyskują na monorepo, większe organizacje z autonomicznymi zespołami częściej wybierają podział, bo koszt koordynacji przewyższa korzyść ze wspólnej historii.
Co nigdy nie powinno trafić do repozytorium kodu?
Przede wszystkim wszystko, co stanowi sekret: hasła do bazy danych, klucze API, tokeny dostępowe, prywatne klucze SSH oraz pliki certyfikatów. Raz wysłany do zdalnej historii sekret należy traktować jako ujawniony, nawet po usunięciu commitu, ponieważ kopie repozytorium istnieją na dyskach współpracowników i w cache serwisów hostingowych. Właściwym miejscem są zmienne środowiskowe, menedżer sekretów lub sejf w narzędziu CI, a do repozytorium trafia wyłącznie plik przykładowy z pustymi wartościami. Do historii nie należą również artefakty budowania, katalogi zależności, zrzuty produkcyjnej bazy danych z danymi osobowymi, pliki IDE oraz materiały graficzne ważące setki megabajtów, dla których lepszym rozwiązaniem jest Git LFS lub zewnętrzny magazyn plików.
