Generator szablonu GitHub Issue

Generator GitHub Issue Template — uporządkowane zgłoszenia w YAML

Generator GitHub Issue Template tworzy poprawny plik formularza zgłoszenia dla repozytorium. Wybierz raport błędu, propozycję funkcji albo konfigurację linków, uzupełnij pola i skopiuj gotowy YAML do .github/ISSUE_TEMPLATE/. Narzędzie cytuje dane, nadaje unikalne identyfikatory i pilnuje schematu Issue Forms.

Issue Forms a klasyczny szablon Markdown

GitHub obsługuje dwa różne mechanizmy, których nie należy mieszać. Klasyczny szablon Markdown ma rozszerzenie .md, opcjonalny blok front matter między separatorami --- i zwykły tekst z komentarzami. Issue Forms to natomiast dokument YAML z rozszerzeniem .yml lub .yaml. Zawiera klucze name, description i body, a GitHub buduje z nich interaktywny formularz.

Jak zbudować formularz zgłoszenia

1. Wybierz preset błędu lub funkcji. Otrzymasz sensowne nazwy, etykiety i zestaw pytań startowych.
2. Dostosuj nazwę, opis i prefiks tytułu widoczny po rozpoczęciu zgłoszenia.
3. Wpisz etykiety oraz loginy osób przypisanych, oddzielając wartości przecinkami. Konta muszą mieć dostęp do repozytorium.
4. Zdefiniuj każde pole w osobnym wierszu: Etykieta | input | placeholder albo Etykieta | textarea | placeholder.
5. Skopiuj wynik do ścieżki pokazanej nad edytorem. Nie dodawaj separatorów front matter.
6. Wykonaj commit i sprawdź zakładkę Issues. Przed publikacją możesz też użyć walidatora YAML.

Pola input i textarea

input jest dobry dla krótkiej, jednoliniowej odpowiedzi: wersji aplikacji, systemu, numeru wydania lub adresu repozytorium demonstracyjnego. textarea służy do opisu problemu, kroków odtworzenia, oczekiwanego zachowania i propozycji rozwiązania. Każde wygenerowane pole ma validations.required: true, więc zgłaszający nie może wysłać pustej odpowiedzi.

Placeholder podpowiada format, lecz znika po rozpoczęciu pisania i nie zastępuje etykiety. Aby w placeholderze textarea pokazać kilka wierszy, wpisz dosłownie \n. Generator zamieni sekwencję na bezpieczny znak nowej linii w cytowanym skalarze YAML.

Unikalne ID i walidacja schematu

Każdy element formularza potrzebuje identyfikatora z liter, cyfr, myślników lub podkreśleń. Generator transliteruje etykietę, usuwa niedozwolone znaki i ogranicza długość ID. Jeśli dwa pola mają tę samą etykietę, kolejne dostaje sufiks, na przykład environment-2. Dzięki temu wynik nie zawiera dwóch kontrolek o identycznym identyfikatorze.

Narzędzie odrzuca pustą nazwę, pusty opis, formularz bez pól, nieobsługiwany typ kontrolki oraz listy przekraczające limity. Dane takie jak dwukropek, #, cudzysłów czy wartości podobne do true są emitowane w cytowanych skalarach. Nie mogą przez to utworzyć nowego klucza ani komentarza YAML.

Etykiety i osoby przypisane

Etykiety pomagają kierować zgłoszenia do odpowiedniej kolejki, np. bug, enhancement lub needs-triage. Muszą już istnieć w repozytorium, inaczej GitHub ich nie zastosuje. Login w assignees powinien należeć do osoby mającej wymagane uprawnienia. Sam plik nie nadaje dostępu i nie tworzy kont.

Dobrze zaprojektowany formularz skraca triage, ale nie zastąpi automatyzacji. Testy i kontrolę jakości możesz skonfigurować w generatorze GitLab CI albo dopasować do własnego GitHub Actions. Jeśli zgłoszenie dotyczy procesu budowania obrazu, spójny przykład przygotujesz z pomocą generatora Dockerfile.

Plik config.yml i linki kontaktowe

Preset konfiguracji tworzy specjalny plik .github/ISSUE_TEMPLATE/config.yml. Ustawienie blank_issues_enabled: false wyłącza możliwość pominięcia formularzy. Sekcja contact_links może skierować pytania do dokumentacji, dyskusji lub pomocy technicznej. Generator wymaga pełnego adresu HTTPS i tworzy jeden link, który można później skopiować i rozbudować ręcznie.

Nie wpisuj w linku tokenu, hasła ani danych sesji. Adres zostaje zapisany w publicznym repozytorium. Użyj stabilnej strony dokumentacji, a nie prywatnego panelu. Jeżeli projekt ma bardziej rozbudowany proces CI, pomocny może być także generator Jenkinsfile do przygotowania powtarzalnego pipeline.

Dobre pytania dają lepsze zgłoszenia

Raport błędu powinien pytać o obserwowane zachowanie, minimalne kroki odtworzenia, wynik oczekiwany i środowisko. Propozycja funkcji powinna rozpoczynać się od problemu użytkownika, a dopiero potem prosić o rozwiązanie i rozważone alternatywy. Unikaj jednego ogromnego pola „Opis”, bo miesza ono fakty, oczekiwania i kontekst.

Nie proś o sekrety, klucze API, prywatne logi ani dane osobowe. Jeśli potrzebujesz logu, wyjaśnij, że należy usunąć tokeny i adresy użytkowników. Dla podatności bezpieczeństwa przygotuj prywatny kanał zgłoszeń zamiast publicznego issue.

Najczęściej zadawane pytania