Dlaczego warto przygotować repozytorium pod kontrybutorów
Projekt prywatny vs projekt społecznościowy
Repozytorium można traktować jak notes z własnymi eksperymentami albo jak produkt, z którego korzystają inni. W pierwszym przypadku wystarczy kilka commitów i ogólny opis. W drugim – brak struktury natychmiast zemści się na czasie i nerwach wszystkich zaangażowanych.
Projekt społecznościowy to taki, do którego potencjalnie może dorzucić się każdy: kodem, tłumaczeniami, dokumentacją czy feedbackiem. Osoby z zewnątrz nie znają historii decyzji, nie wiedzą, gdzie leży „prawda” o projekcie, jakie są standardy, ani jak „tu się rzeczy robi”. Dlatego repozytorium musi im to jasno pokazać.
Różnica w praktyce jest prosta:
- „Mój projekt na GitHubie” – ja wiem, jak to uruchomić, ja wiem, co jest ważne, zgłoszenia prawie nie przychodzą.
- Projekt społecznościowy – dokumentacja prowadzi za rękę, kontrybutorzy potrafią sami rozwiązać większość wątpliwości, a maintainer nie jest wąskim gardłem.
Bez tej mentalnej zmiany każdy nowy kontrybutor będzie zadawał te same pytania, a Ty będziesz je w kółko odpisywać zamiast rozwijać projekt.
Co się dzieje, gdy brakuje jasnych zasad
Brak README, CONTRIBUTING i szablonów zgłoszeń nie oznacza „mniej biurokracji”. Oznacza chaos w komunikacji. Typowe skutki są bardzo przewidywalne:
- Duplikaty issue – po kilku miesiącach masz kilka zgłoszeń tego samego błędu, każde opisane inaczej, bez wspólnego numeru referencyjnego.
- Konflikty i nieporozumienia – ktoś przygotował duży Pull Request, który nie pasuje do wizji projektu, bo nigdzie nie opisałeś roadmapy ani zakresu.
- Porzucone PR-y – autor nie wie, co poprawić, recenzja ciągnie się tygodniami, nikt nie czuje się odpowiedzialny.
- Poczucie niesprawiedliwości – jedna osoba dostała szczegółowy code review, inna lakoniczne „nie przejdzie”, bez wyjaśnienia.
Brak zasad nie oznacza braku reguł – oznacza, że reguły powstają ad hoc, w głowach maintainerów, często niespójnie. Dokumenty repozytorium po prostu je ujawniają i porządkują, zanim dojdzie do pierwszego konfliktu.
Koszt kontrybucji dla nowych i dla maintainerów
Każda kontrybucja ma swój koszt. Z perspektywy nowej osoby:
- musi zrozumieć, czym jest projekt i czy w ogóle potrzebuje jej wkładu,
- musi uruchomić środowisko, przebrnąć przez zależności,
- musi dowiedzieć się, jak wysłać zmianę tak, żeby nie przeszkadzać.
Z perspektywy maintainerów koszt jest jeszcze większy, jeśli repo nie jest przygotowane:
- ciągłe odpowiadanie na te same pytania („jak odpalić testy?”, „jaką wersję Node używacie?”),
- gaszenie pożarów – błędy wprowadzane przez osoby, które nie znały procesu,
- emocjonalne zmęczenie ciągłym odrzucaniem PR-ów, które od początku nie miały szans przejść.
Dobre README, CONTRIBUTING i szablony issue/PR drastycznie obniżają ten koszt. Nowy kontrybutor może przejść onboarding samodzielnie. Maintainer wchodzi w proces dopiero wtedy, gdy wkład ma sens i jest dobrze przygotowany.
Wpływ dobrego przygotowania repozytorium na tempo rozwoju
Uporządkowane repozytorium działa jak filtr i akcelerator. Filtr – bo zniechęca osoby, które chciałyby „wrzucić byle co”, ale nie chce im się przejść przez minimum formalności. Akcelerator – bo pomaga tym, którzy na serio chcą pomóc, szybko dotrzeć do jakościowego wkładu.
Praktyczne efekty:
- Lepsza jakość zgłoszeń – jedno dopracowane issue zamiast pięciu ogólnikowych.
- Szybsze review – PR ma opis, checklistę, informację o testach, więc recenzent nie spędza połowy czasu na dopytywaniu.
- Mniej błędów po wdrożeniu – jasne wymagania (testy, lint, styl commitów) redukują „przepchane” zmiany.
Repozytorium przyjazne społeczności staje się atrakcyjne dla kontrybutorów. Nowi chętniej wracają, bo wiedzą, czego się spodziewać. To przekłada się na stabilny, przewidywalny rozwój, zamiast jednorazowych „zrywów” i długich okresów stagnacji.
Minimalny zestaw plików dla projektu społecznościowego
Kluczowe pliki i ich rola
W większości projektów społecznościowych przewijają się te same podstawowe pliki. Każdy ma konkretne zadanie:
- README.md – pierwszy kontakt z projektem, mapa i „landing page” repozytorium.
- CONTRIBUTING.md – instrukcja, jak w praktyce kontrybuować (kod, dokumentacja, zgłoszenia).
- CODE_OF_CONDUCT.md – kodeks postępowania, zasady komunikacji i konsekwencje naruszeń.
- LICENSE – licencja, która jasno mówi, co wolno robić z kodem.
- SECURITY.md – sposób zgłaszania luk bezpieczeństwa (tajny kanał zamiast publicznego issue).
- FUNDING.yml / FUNDING.md – informacje o wsparciu finansowym projektu (GitHub Sponsors, Open Collective itd.).
Ten zestaw nie jest „dla dużych graczy”. Nawet małe narzędzie CLI używane przez kilka osób z zewnątrz zyskuje na takim porządku. Użytkownik wie, gdzie szukać odpowiedzi na konkretne typy pytań.
Gdzie umieścić pliki i jak są wyświetlane
Najważniejsze pliki zawsze leżą w katalogu głównym repozytorium (root):
README.md– GitHub/GitLab pokazuje go automatycznie na stronie głównej repo.CONTRIBUTING.md– GitHub linkuje go przy tworzeniu issue/PR („Please read the contribution guidelines”).CODE_OF_CONDUCT.md,LICENSE– często rozpoznawane przez platformę i prezentowane w interfejsie.SECURITY.md– GitHub ma dedykowaną sekcję „Security” z odnośnikiem do tego pliku.
Szablony zgłoszeń i dodatkowe konfiguracje zwykle trafiają do katalogów takich jak .github/ (GitHub) czy .gitlab/ (GitLab). O tym szerzej w osobnej sekcji, ale ogólny schemat jest prosty: główne zasady na wierzchu, szablony w katalogu konfiguracyjnym.
Absolutne minimum vs elementy do dodania później
Dla całkiem małego projektu, który dopiero otwiera się na świat, da się wskazać absolutne minimum:
- README.md z opisem, szybkim startem i informacją, jak zgłaszać błędy.
- LICENSE – bez licencji wiele osób w ogóle nie zechce kontrybuować.
- Prosty CONTRIBUTING.md z 1–2 stronami konkretnych instrukcji.
Pozostałe pliki można dodać stopniowo, gdy rośnie liczba użytkowników i zgłoszeń:
- CODE_OF_CONDUCT – warto dodać, gdy pojawiają się pierwsze interakcje w issues/PR-ach.
- SECURITY.md – gdy projekt jest używany w środowiskach produkcyjnych lub dotyka bezpieczeństwa.
- FUNDING – gdy ktoś pyta, jak może wesprzeć projekt.
Strategia „najpierw porządne core pliki, potem dodatki” pomaga nie ugrzęznąć w dopieszczaniu dokumentacji przy projekcie, który jeszcze nie ma użytkowników.
Mały projekt a większa organizacja – inne podejście
W jednoosobowym repozytorium możesz sobie pozwolić na bardziej osobisty ton, prostsze procesy i mniejszą formalizację. W większej organizacji lub przy wielu maintainerach spójność i standaryzacja stają się ważniejsze.
Dla małego projektu:
- krótszy CONTRIBUTING, bardziej elastyczne zasady,
- mniej formalne opisy („Napisz do mnie na…”, „Zobaczymy, czy to pasuje do roadmapy”).
Dla większej organizacji:
- szablony współdzielone w repozytorium organizacji,
- jasne role (maintainer, reviewer, triager),
- formalny kodeks postępowania i procedury eskalacji.
W obu przypadkach kluczowe jest jedno: zapisz realne praktyki. Nie twórz dokumentów na pokaz. Jeżeli w projekcie naprawdę wymagasz review dwóch maintainerów – wpisz to. Jeśli nie – nie udawaj, że tak jest.
README jako mapa projektu – kluczowe elementy
Krótki, konkretny opis celu projektu
Dobry README zaczyna się od odpowiedzi na trzy pytania: co to jest, po co to jest i dla kogo. Najlepiej zamknąć to w jednym–dwóch akapitach, bez marketingowego nadęcia.
Przykład prostego wstępu:
„Narzędzie CLI do zarządzania konfiguracją wielu środowisk Node.js w jednym repozytorium. Ułatwia przełączanie się między konfiguracjami dev/stage/prod i generuje pliki .env na podstawie szablonów.”
Taki opis pozwala nowej osobie szybko ocenić, czy projekt jej dotyczy. Unika się sytuacji, w której ktoś czyta kilkanaście akapitów, zanim zrozumie, że to w ogóle nie jest narzędzie dla niego.
Sekcja „Szybki start” – od zera do działającego przykładu
Najbardziej praktyczny element README to „Quick start” (albo „Szybki start”). Dobrze przygotowana sekcja odpowiada na pytanie: „Co muszę wklepać w terminal, aby to w ogóle ruszyło?”.
Typowy schemat:
- wymagania wstępne (np. „wymagany Python >=3.10, pip, Git”),
- komendy instalacji (np.
git clone,npm install,pip install), - komenda uruchomienia (np.
npm start,docker compose up), - najprostszy przykład użycia (request, komenda, wywołanie biblioteki).
Dobrze, gdy „Szybki start” jest możliwie krótki, bez zbędnych opcji i zastrzeżeń. Zaawansowane scenariusze można opisać w osobnej dokumentacji, a w README zostawić tylko ścieżkę „happy path”.
Informacja dla kogo jest projekt i jakie ma ograniczenia
README często milczy na temat ograniczeń, przez co rodzi się sporo nieporozumień. Warto jasno napisać:
- dla jakiego typu użytkowników/projektów to rozwiązanie jest sensowne,
- czego nie wspiera (np. „brak wsparcia dla Windows”, „obsługujemy wyłącznie PostgreSQL”).
Taka sekcja może się nazywać np. „Zakres i ograniczenia” albo „Dla kogo to jest / dla kogo nie jest”. Pozwala to uniknąć issue typu „dlaczego to nie działa na Windows 7?” przy projekcie, który od początku nie planował takiego wsparcia.
Linki do dalszych materiałów i zasad współpracy
README powinien działać jak rozdzielacz. Po wstępnym zapoznaniu użytkownik powinien mieć jasne ścieżki:
- „Chcę używać” – link do pełnej dokumentacji / wiki.
- „Chcę zgłosić błąd” – link do zasad zgłaszania issue i ewentualnie
SECURITY.md. - „Chcę kontrybuować” – link do
CONTRIBUTING.md. - „Chcę wesprzeć” – link do sekcji wsparcia /
FUNDING.
Zamiast wrzucać wszystko do jednego dokumentu, lepiej podzielić informacje na wyspecjalizowane pliki i w README podlinkować je w sekcji „Dalsze kroki” lub „Przydatne linki”.
Odznaki w README – jak używać ich z głową
Odznaki (badges) potrafią uprościć życie: pokazują status builda, pokrycie testami, wersję na npm/PyPI, licencję itd. Problem zaczyna się, gdy README zamienia się w ścianę kolorowych etykietek zajmujących pół ekranu.
Rozsądne zasady:
- umieszczaj odznaki na samej górze, ale ogranicz ich liczbę do kilku kluczowych,
- stawiaj na informację praktyczną: build status, licencja, ostatnie wydanie,
- odrzucaj „ego badges” typu „made with ❤️” – to przeszkadza w skanowaniu treści.
Odznaki są szczególnie przydatne dla kontrybutorów – status CI mówi im, czy repo jest w dobrym stanie, a wersja języka/platformy pozwala ocenić, czy ich środowisko lokalne będzie kompatybilne.
Jak napisać CONTRIBUTING, który prowadzi za rękę
Po co osobny plik CONTRIBUTING, skoro jest README
Różne poziomy szczegółowości dla różnych typów kontrybucji
Jedna z pułapek CONTRIBUTING.md to wrzucenie wszystkiego do jednego, długiego dokumentu. Lepsze podejście to podział na ścieżki, które odpowiadają realnym typom wkładu:
- „Jak zgłosić błąd” – dla osób, które nie zamierzają pisać kodu.
- „Jak dodać lub poprawić funkcję” – dla programistów.
- „Jak poprawić dokumentację” – dla osób nietechnicznych.
- „Jak pomóc w triage” – dla bardziej zaangażowanych.
Można to zorganizować jako krótką tabelkę lub wypunktowaną listę na początku CONTRIBUTING, gdzie każdy punkt linkuje do osobnej sekcji lub nawet osobnego pliku w katalogu docs/ czy .github/. Kontrybutor nie musi czytać całego „regulaminu”, tylko przechodzi do fragmentu, który go dotyczy.
Minimalna struktura CONTRIBUTING.md
Dokument może być prosty, ale powinien mieć kilka stałych bloków. Przykładowa struktura, która sprawdza się w większości projektów:
- Jak zgłaszać błędy i propozycje funkcji
- Jak przygotować środowisko developerskie
- Jak pisać i uruchamiać testy
- Styl kodu i konwencje commitów
- Workflow Pull Requestów
- Kontakt i kanały komunikacji
Jeżeli projekt rośnie, te sekcje można wydzielić do osobnych plików (np. docs/testing.md, docs/dev-setup.md), a w CONTRIBUTING zostawić krótkie streszczenia z linkami. Dzięki temu dokument pozostaje czytelny, a osoby szukające szczegółów mają gdzie kliknąć.
Instrukcja zgłaszania błędów i pomysłów – krok po kroku
Większość osób zaczyna od zgłoszenia bugów lub pomysłów. Dobrze opisany proces potrafi radykalnie obniżyć hałas w issue trackerze. Przydatna jest prosta sekwencja kroków:
- link do wyszukiwarki issue z zachętą, by najpierw sprawdzić duplikaty,
- podlinkowanie szablonu (o nich dalej) z krótkim komentarzem „wypełnij możliwie dokładnie”,
- prośba o minimalny przykład reprodukcji + konkretne środowisko (system, wersje bibliotek),
- wskazanie, jak oznaczać typ zgłoszenia (np. etykiety „bug”, „feature request” są ustawiane przez maintainerów, więc nie trzeba się tym przejmować).
Na końcu tej sekcji można dodać jedno zdanie, które ustawia oczekiwania czasowe, np.: „Zwykle odpowiadamy w ciągu 7 dni, ale projekt jest rozwijany po godzinach – prosimy o cierpliwość.”. To oszczędza zniecierpliwionych komentarzy po 24 godzinach ciszy.
Setup środowiska developerskiego bez domysłów
Druga krytyczna część CONTRIBUTING to instrukcja „zbuduj i odpal projekt lokalnie”. Im mniej zgadywania, tym mniejsza bariera wejścia. Pomocny schemat:
- lista wspieranych wersji języka / runtime (np. „Node 20 LTS, Yarn 4”),
- kroki instalacji zależności systemowych (bazy danych, narzędzia CLI),
- komendy do uruchomienia projektu w trybie developerskim,
- wzmianka o typowych problemach (np. „jeśli na macOS pojawi się błąd X, zainstaluj Y”).
Dla bardziej skomplikowanych projektów dobrym rozwiązaniem jest plik Makefile albo skrypt ./scripts/dev.sh z jedną komendą make dev czy ./scripts/dev.sh. W CONTRIBUTING wystarczy wtedy prosty fragment:
git clone https://github.com/org/projekt.git
cd projekt
make dev
Kontrybutor nie musi wiedzieć, jakie dokładnie komendy są uruchamiane, dopóki środowisko startuje poprawnie.
Testy: jakie, jak je uruchomić i czy są obowiązkowe
Wielu nowych kontrybutorów nie ma pewności, czy powinni dopisywać testy. Brak jasnego komunikatu kończy się PR-ami bez pokrycia lub dyskusjami w komentarzach. Klarowna sekcja „Testy” rozwiązuje sprawę:
- jedna komenda do uruchomienia wszystkich testów,
- instrukcja, gdzie dodać nowe testy (np. katalog, konwencja nazewnicza),
- informacja, czy testy są wymagane dla każdego PR-a, czy tylko dla zmian w określonych częściach kodu,
- link do dodatkowej dokumentacji testów, jeśli taka istnieje.
Przykładowy, konkretny zapis:
- „Zmiany w katalogach
src/iapi/wymagają testów jednostkowych. Zmiany w dokumentacji nie wymagają testów.” - „Uruchom
npm testprzed wysłaniem PR. CI zablokuje merge, jeśli testy nie przejdą.”
Taki fragment ustawia standard, ale nie odstrasza – każdy wie, czego się spodziewać.
Styl kodu i commitów – mniej dyskusji, więcej automatyzacji
Spory o styl kodu są najgorszym możliwym sposobem spędzania czasu maintainerów. Dużo lepiej zainwestować w prosty zestaw zasad i narzędzia, które je egzekwują:
- link do plików konfiguracyjnych (np.
.editorconfig,.eslintrc,pyproject.toml), - komenda „lint” (np.
npm run lint,ruff check .), - informacja, czy lint musi przejść lokalnie przed wysłaniem PR-a,
- krótki przykład poprawnego komunikatu commita (np. konwencja Conventional Commits).
Przykład z życia: w jednym z projektów wprowadzenie hooków pre-commit oraz sekcji w CONTRIBUTING:
pip install pre-commit
pre-commit install
zredukowało liczbę „kosmetycznych” komentarzy w review o kilkadziesiąt procent. Lint i formatowanie załatwiał automat, a dyskusje toczyły się wokół logiki.
Workflow PR-ów opisany jak scenariusz
Nowe osoby często nie wiedzą, jak „poprawnie” wchodzić w istniejący proces. Przydaje się opis etapów PR-a:
- Załóż issue lub podłącz się do istniejącego (jeśli wymagane).
- Utwórz gałąź z
main/developwedług konwencji nazewniczej. - Wprowadź zmiany, dodaj testy, uruchom linters/testy lokalnie.
- Wyślij PR z wypełnionym szablonem i linkiem do powiązanego issue.
- Odpowiadaj na komentarze review, aktualizuj PR commitami.
- Maintainer scala PR po spełnieniu kryteriów.
Warto też dodać sekcję „Zakres PR-a”, np.: „Jedno logiczne usprawnienie na PR. Nie mieszaj refactoringu i nowych funkcji.”. Taki zapis bardzo ułatwia życie osobom robiącym review.
Przykładowy szkielet CONTRIBUTING.md
Krótkie szkielety pomagają szybciej wystartować. Minimalny przykład:
# Zasady kontrybucji
## Zgłaszanie błędów i pomysłów
- Sprawdź istniejące zgłoszenia: <link>
- Użyj odpowiedniego szablonu issue
- Dodaj kroki reprodukcji i wersję środowiska
## Środowisko developerskie
- Wymagany: Node 20, Docker
- Instalacja: `npm install`
- Start: `npm run dev`
## Testy
- Uruchom: `npm test`
- Nowe funkcje wymagają testów jednostkowych
## Styl kodu i commity
- Formatowanie: `npm run lint` i `npm run format`
- Stosujemy Conventional Commits, np. `feat:`, `fix:`, `docs:`
## Pull Requesty
- Jedna funkcja / fix na PR
- Wypełnij szablon PR
- Podlinkuj powiązane issue
Taki dokument można potem rozszerzać, ale już w tej formie bardzo pomaga nowym osobom.
Kodeks postępowania i zasady komunikacji
Dlaczego sam „dobry charakter” maintainerów nie wystarczy
W małym, nieformalnym projekcie wszystko działa, dopóki uczestnicy się znają. Gdy dołączają nieznane osoby z internetu, „domyślne” normy przestają być czytelne. Kodeks postępowania (Code of Conduct) ustawia oczekiwania i daje ramy reagowania na problemy.
Chodzi zarówno o duże naruszenia (obraźliwe komentarze), jak i codzienną kulturę współpracy: jak prosić o zmiany, jak reagować na feedback, co jest akceptowalne w dyskusji technicznej. Zapisanie tego na piśmie zmniejsza ryzyko konfliktów i ułatwia interwencję, gdy coś wymknie się spod kontroli.
Gotowe szablony kodeksu postępowania
Nie ma sensu wymyślać wszystkiego od zera. Kilka sprawdzonych opcji:
- Contributor Covenant – najpopularniejszy, wspierany przez GitHub jako domyślna opcja.
- Citizen Code of Conduct – nieco inne akcenty, często używany na wydarzeniach.
- Własny, uproszczony CoC – dla małych projektów, oparty na 2–3 podstawowych zasadach.
Dobrą praktyką jest użycie Contributor Covenant w wersji zlokalizowanej (jeśli kontrybutorzy posługują się głównie polskim) i lekkie dopasowanie, np. danych kontaktowych do zgłaszania naruszeń.
Elementy, które kodeks powinien zawierać
Niezależnie od wybranego szablonu, przydaje się kilka konkretnych bloków:
- opis akceptowalnego zachowania (uprzejma komunikacja, konstruktywny feedback),
- przykłady zachowań nieakceptowalnych (atak personalny, seksistowskie komentarze, „nawalanie” caps lockiem),
- opis ról – kto może reagować (maintainerzy, moderatorzy),
- procedura zgłaszania naruszeń (adres e-mail, formularz, prywatne wiadomości),
- potencjalne konsekwencje (ostrzeżenie, zablokowanie konta, zgłoszenie do platformy).
Najważniejszy jest realistyczny, wykonalny mechanizm egzekwowania. Jeżeli utrzymujesz projekt po godzinach i nie masz czasu na formalne dochodzenia, wpisz to wprost i uprość procedurę – lepiej obiecać mniej, niż deklarować skomplikowany proces, którego nikt później nie zrealizuje.
Gdzie umieścić CoC i jak do niego odwoływać się w praktyce
Standard to plik CODE_OF_CONDUCT.md w katalogu głównym repo. GitHub automatycznie wykryje ten dokument i podlinkuje go w interfejsie. Dodatkowo można:
- podlinkować CoC w README w sekcji „Zasady współpracy”,
- wspomnieć o nim w CONTRIBUTING („Uczestnicząc w projekcie, akceptujesz nasz Kodeks postępowania.”),
- zamieścić skróconą wersję kluczowych zasad w szablonach issue/PR.
W praktyce wiele konfliktów rozwiązuje jedno spokojne odwołanie do zapisanej zasady, np.: „W naszym CoC prosimy o unikanie personalnych uwag. Skupmy się na kodzie, a nie na osobach.”.
Ustalony ton komunikacji – asynchronicznie i rzeczowo
Oprócz CoC przydają się spisane zasady komunikacji, zwłaszcza gdy projekt korzysta z kilku kanałów: GitHub Issues, Slack, Discord, e-mail. Kilka prostych reguł potrafi znacząco poprawić komfort pracy:
- preferowany kanał do konkretnych spraw (bugi → issues, pytania ogólne → GitHub Discussions / forum),
- zasada „no @here / @everyone” bez wyraźnej potrzeby,
- dopuszczalne języki (np. angielski jako domyślny przy międzynarodowej społeczności),
- oczekiwany czas reakcji (np. „dias, nie godziny”).
Te reguły można opisać w osobnej sekcji CONTRIBUTING lub w pliku COMMUNICATION.md i podlinkować. Im mniej domysłów, tym mniej rozczarowań po obu stronach.
Jak reagować na trudne sytuacje z kontrybutorami
Konflikty się zdarzają: ktoś nie przyjmuje feedbacku, powtarza to samo pytanie w kilku kanałach, publikuje pasywno-agresywne komentarze. Dobrze mieć przygotowany, spójny sposób reagowania:
- Jednokrotne, spokojne wyjaśnienie zasady i prośba o zmianę zachowania.
- Jeśli problem wraca – powołanie się na konkretny punkt CoC i zapowiedź konsekwencji.
- Ostatecznie – zablokowanie użytkownika i krótkie, rzeczowe uzasadnienie.
W CoC można wprost napisać, że maintainerzy mają prawo priorytetyzować własne bezpieczeństwo i komfort, wobec czego nie muszą angażować się w niekończące się dyskusje z jedną osobą. Dla większości osób sam fakt, że zasady są spisane, działa prewencyjnie.
Szablony issue – porządek w zgłoszeniach
Po co szablony, skoro można napisać „opisz problem”
Jak dobre szablony zmieniają jakość zgłoszeń
Luźne pole tekstowe zachęca do luźnych zgłoszeń. Efekt: „nie działa”, „naprawcie to” albo zrzut ekranu bez kontekstu. Szablon issue wymusza minimalną strukturę i prowadzi osobę zgłaszającą krok po kroku. Mniej czasu tracisz na dopytywanie, szybciej klasyfikujesz zgłoszenia.
Dobry szablon:
- zadaje konkretne pytania (co się stało, gdzie, w jakiej wersji),
- oddziela bugi od propozycji funkcji,
- podsuwa gotowe sekcje typu „Kroki reprodukcji”, „Oczekiwane zachowanie”,
- przypomina o sprawdzeniu duplikatów i dokumentacji.
Po wdrożeniu szablonów w wielu projektach kończą się serie komentarzy „jaka wersja?”, „jaki system?”, „masz logi?”. To wszystko jest w pierwszej wiadomości.
Typy szablonów issue – nie jeden, tylko kilka
Jeden szablon do wszystkiego szybko się rozpada. Inne informacje są potrzebne przy błędzie, inne przy prośbie o funkcję, a jeszcze inne przy pytaniu „jak tego użyć?”. Lepsze podejście:
- osobny szablon Bug report,
- osobny szablon Feature request / Improvement,
- opcjonalny szablon Question / Support (albo link do innego kanału).
Na GitHubie przy szablonach opartych na YAML możesz skonfigurować „formularze” z checkboxami i polami tekstowymi. Dobrze działa np. checkbox „Przeczytałem dokumentację” lub „Sprawdziłem istniejące zgłoszenia”. To delikatny filtr na zgłoszenia z nudów.
Minimalny szablon zgłoszenia błędu
Praktyczny, nieprzeładowany szablon błędu może wyglądać tak:
name: Bug report
description: Zgłoszenie błędu w działaniu aplikacji
labels: [bug]
body:
- type: markdown
attributes:
value: |
Dziękujemy za zgłoszenie błędu! Uzupełnij proszę wszystkie sekcje.
- type: input
id: summary
attributes:
label: Krótki opis
description: Jedno zdanie, co jest nie tak.
placeholder: Np. "Aplikacja zawiesza się przy zapisie formularza"
validations:
required: true
- type: textarea
id: steps
attributes:
label: Kroki reprodukcji
description: Jak powtórzyć problem krok po kroku.
placeholder: |
1. Wejdź na stronę ...
2. Kliknij ...
3. Zobacz błąd ...
validations:
required: true
- type: textarea
id: behavior
attributes:
label: Oczekiwane vs aktualne zachowanie
description: Co miało się stać, a co stało się w rzeczywistości?
validations:
required: true
- type: input
id: version
attributes:
label: Wersja i środowisko
placeholder: Np. v1.4.2, Chrome 120, Windows 11 / Ubuntu 22.04
validations:
required: true
- type: textarea
id: logs
attributes:
label: Logi lub zrzuty ekranu
description: Jeśli to możliwe, wklej logi (otocz je ```), dołącz screeny.
render: shell
To naprawdę wystarczy, żeby odsiać zgłoszenia typu „nie działa, naprawcie”. Przy mniejszych projektach można zrezygnować z części pól, ale „Kroki reprodukcji” i „Środowisko” powinny zostać.
Szablon propozycji funkcji – skupienie na problemie, nie na rozwiązaniu
Przy prośbach o nowe funkcje chaos bywa jeszcze większy niż przy bugach. Dobrze zaprojektowany szablon kieruje rozmowę na problem użytkownika, a nie na konkretną implementację.
name: Feature request
description: Propozycja nowej funkcji lub usprawnienia
labels: [enhancement]
body:
- type: textarea
id: problem
attributes:
label: Jaki problem chcesz rozwiązać?
description: Opisz sytuację, w której brakuje Ci tej funkcji.
placeholder: |
Np. "Przy wielu projektach trudno mi znaleźć konkretne zadanie,
bo lista jest nieposortowana."
validations:
required: true
- type: textarea
id: proposal
attributes:
label: Opis proponowanego rozwiązania
description: Jak wyobrażasz sobie działanie funkcji?
validations:
required: true
- type: textarea
id: alternatives
attributes:
label: Jakie alternatywy rozważałeś(aś)?
description: Opisz inne podejścia, których próbowałeś(aś).
validations:
required: false
- type: textarea
id: extra
attributes:
label: Dodatkowy kontekst
description: Linki, przykłady z innych narzędzi, mockupy.
Tak ułożony szablon pomaga ocenić, czy problem jest powszechny, czy dotyczy wąskiej niszy i czy ma sens w core projektu. Ułatwia też zamykanie próśb w stylu „zróbcie wszystko inaczej” – można się odnieść do wypisanych potrzeb.
Instrukcja na górze formularza – mały tekst, duży efekt
Sam formularz to nie wszystko. Krótkie wprowadzenie w pierwszym bloku markdown robi ogromną różnicę. Można tam jasno napisać:
- „Zgłoszenia bez kroków reprodukcji mogą zostać zamknięte jako niewystarczająco opisane.”
- „Jeśli masz pytanie o użycie biblioteki, użyj najpierw Discussions / Stack Overflow.”
- „Nie publikuj tu haseł, tokenów ani wrażliwych danych z logów.”
Taki komunikat ustawia oczekiwania przed kliknięciem „Submit”. W wielu przypadkach eliminuje zgłoszenia supportowe, które w ogóle nie powinny trafić do issue trackera.
Szablony a etykiety i automatyzacja triage
Dobrze skonfigurowane szablony współpracują z etykietami (labels). Przy formularzach YAML na GitHubie można przypisać domyślne etykiety:
bugdla szablonu błędu,enhancementlubfeaturedla propozycji,questiondla pytań (jeśli je dopuszczasz).
To otwiera drogę do prostych automatów (GitHub Actions, Probot):
- robot wita nowe zgłoszenia określonego typu i odsyła do dokumentacji,
- niekompletne zgłoszenia z określonym label mogą być automatycznie zamykane po X dniach bez reakcji,
- określone etykiety mogą automatycznie przypisywać maintainerów do review.
Przy większej liczbie zgłoszeń taki system triage oszczędza godziny żmudnego przeklikiwania.
Jak iterować nad szablonami na podstawie realnych zgłoszeń
Szablony nie są raz na zawsze. Dobry nawyk: raz na kwartał przejrzeć zgłoszenia i zadać sobie dwa pytania:
- Jakich informacji ciągle brakuje, mimo formularza?
- Które pola są nagminnie ignorowane lub wypełniane bez sensu?
Na tej podstawie można:
- oznaczyć brakujące pola jako wymagane,
- połączyć zbyt szczegółowe sekcje w jedno pole,
- dodać krótkie przykłady do placeholderów.
Przykład z praktyki: po kilku zgłoszeniach „nie ładuje się strona” okazało się, że nikt nie podaje informacji o przeglądarce i ad blockerach. Dodanie jednego pola „Przeglądarka, system, rozszerzenia (szczególnie adblock)” nagle wyjaśniło większość przypadków.
Szablony Pull Requestów – mniej pytań, lepsze review
Po co narzucać strukturę PR-a
Pull Request bez opisu to koszmar dla reviewera. Trzeba przegryźć się przez diff, domyślić się intencji, szukać potencjalnych regresji. Szablon PR-a rozwiązuje ten problem: wymusza krótkie podsumowanie, link do issue, informację o testach i potencjalnych ryzykach.
Efekt uboczny jest bardzo korzystny – osoba wysyłająca PR często sama zauważa problemy podczas wypełniania formularza („chyba jednak dotykam zbyt wielu rzeczy na raz”).
Kluczowe sekcje w szablonie PR
Niezależnie od stosu technologicznego, przydają się powtarzalne bloki:
- Opis zmian – 2–3 zdania zamiast „patrz diff”.
- Powiązane issue – link
Closes #123lubFixes #123. - Checklist – krótka lista oczywistych kroków.
- Screeny / nagrania – przy zmianach UI.
- Wpływ na kompatybilność – breaking changes, migracje.
Na GitHubie można użyć prostego pliku markdown .github/pull_request_template.md albo nowszego systemu opartych na YAML formularzy (podobnie jak przy issue). Markdown jest jednak wystarczający w większości projektów.
Przykładowy szablon PR w Markdown
## Opis zmian
Krótko opisz, co zostało zmienione i dlaczego.
- ...
## Powiązane issue
Powiązane zgłoszenia:
- Closes #123
## Jak testować
Opisz, jak reviewer może zweryfikować zmiany lokalnie.
1. `npm install`
2. `npm run dev`
3. Wejdź na <URL> i sprawdź ...
## Checklist
- [ ] Zmiany są opisane w README / dokumentacji (jeśli dotyczy)
- [ ] Dodałem(am) testy pokrywające nowe zachowanie
- [ ] `npm test` przechodzi lokalnie
- [ ] Sprawdziłem(am) działanie w <przeglądarka / system> (jeśli dotyczy UI)
## Zmiany łamiące kompatybilność (breaking changes)
- [ ] Tak
- [ ] Nie
Jeśli tak, opisz krótko, co trzeba zmigrować:
Taki szablon jest prosty do skopiowania do większości projektów. Sekcję „Checklist” można dopasować do konkretnych narzędzi, np. dodać „Uruchomiłem(am) pre-commit” lub „Zaktualizowałem(am) schemat bazy”.
PR-y dokumentacyjne i drobne poprawki – osobny, lżejszy szablon
Nie każde zgłoszenie wymaga pełnego formularza. Przy małych poprawkach (literówki, drobne zmiany w dokumentacji) rozbudowany szablon bardziej przeszkadza niż pomaga. Dobrze jest przygotować drugi, uproszczony szablon, np.:
## Rodzaj zmian
- [ ] Poprawka w dokumentacji
- [ ] Literówka / kosmetyka
- [ ] Inne (krótkie wyjaśnienie poniżej)
## Opis
Krótko opisz, co zostało poprawione.
Na GitHubie można skonfigurować wiele szablonów PR (folder .github/PULL_REQUEST_TEMPLATE/) i pozwolić kontrybutorom wybrać odpowiedni podczas tworzenia PR-a. Zmniejsza to frustrację przy prostych wkładach i zachęca nowe osoby do zaczynania od małych rzeczy.
Checklisty dopasowane do projektu – małe przypomnienia
Najlepsze checklisty są krótkie i szyte na miarę. Zamiast ogólnego „zrobiłem wszystko”, lepiej pytania z życia codziennego projektu, np.:
- „[ ] Dodałem(am) wpis do CHANGELOG.md (jeśli zmiana jest widoczna dla użytkownika).”
- „[ ] Sprawdziłem(am) logi po wdrożeniu migracji bazy (jeśli dotyczy).”
- „[ ] Zweryfikowałem(am) responsywność na mobilu (przy zmianach UI).”
To proste przypomnienia, ale realnie zmniejszają liczbę „zapomniałem dodać…”. W dużych projektach potrafią uciąć sporą część regresji.
Jak egzekwować korzystanie ze szablonów PR
Sam plik szablonu nie gwarantuje, że ludzie go wypełnią. Kilka sposobów, żeby nie wracać do punktu wyjścia:
- podkreślenie w CONTRIBUTING, że PR bez opisu może zostać zamknięty,
- użycie GitHub Actions / botów, które przypominają, gdy kluczowe sekcje są puste (np.
<!-- opisz zmiany -->w treści), - dobre nawyki maintainerów: uprzejme, ale konsekwentne „proszę uzupełnić sekcję X, wtedy wrócimy do review”.
Po kilku takich interakcjach większość stałych kontrybutorów automatycznie wypełnia szablon. Nowi uczą się na przykładzie.
Struktura katalogu z plikami meta – gdzie trzymać szablony i zasady
Standardowa struktura na GitHubie
GitHub ma kilka „magicznych” miejsc, które automatycznie wykrywa:
.github/ISSUE_TEMPLATE/– szablony zgłoszeń (Markdown lub YAML),.github/ISSUE_TEMPLATE/config.yml– konfiguracja formularzy,.github/pull_request_template.mdlub.github/PULL_REQUEST_TEMPLATE/– szablony PR-ów,.github/FUNDING.yml– linki do sponsorowania,.github/workflows/– pliki GitHub Actions (CI/CD).
Pliki takie jak README.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md najczęściej trzyma się w katalogu głównym repozytorium, bo GitHub podlinkowuje je w UI, a użytkownik od razu je widzi.
