Poradniki projektów

Szablon informacji o wydaniu GitHub dla projektu open source

Dobre informacje o wydaniu mówią użytkownikowi, czy warto zaktualizować projekt i co zrobić dalej. Lista scalonych pull requestów jest przydatnym źródłem, ale rzadko wyjaśnia cały przebieg aktualizacji. Przed publikacją dodaj wpływ na użytkownika i wymagane działania.

Zespół redakcyjny GitHubStart · Zaktualizowano

Zacznij od szablonu skoncentrowanego na użytkowniku

Zastąp każde pole w nawiasach sprawdzoną informacją. Usuń niepasujące sekcje zamiast wymyślać funkcje. Jeśli aktualizacja nie wymaga dodatkowych działań, napisz to wyraźnie po sprawdzeniu obsługiwanej ścieżki aktualizacji.

# [Wersja] — [Data wydania]

## Najważniejsze zmiany
- [Ulepszenie widoczne dla użytkownika i jego odbiorcy]

## Aktualizacja
- Z wersji: [obsługiwana poprzednia wersja]
- Działanie: [wymagana migracja lub brak dodatkowych działań]
- Weryfikacja: [jak potwierdzić poprawną aktualizację]

## Zmiany niezgodne wstecznie
- [Zmienione zachowanie, dotknięci użytkownicy i link do migracji]

## Poprawki
- [Rozwiązany problem i link do zgłoszenia lub pull requesta]

## Znane problemy
- [Pozostałe ograniczenie i obejście]

## Współtwórcy
[Podziękowania i link do pełnego dziennika zmian]

Zamień wygenerowane notatki w czytelne wyjaśnienie

GitHub może wygenerować notatki zawierające scalone pull requesty, współtwórców i link do pełnego dziennika zmian. Traktuj wynik jako szkic. Sprawdź zakres wydania, usuń nieistotne wpisy i pogrupuj zmiany według zadań wykonywanych przez użytkowników.

Na przykład „Poprawiono przypadek brzegowy parsera” niewiele wyjaśnia. Jeśli to prawda, napisz, że pliki CSV z pustą ostatnią kolumną są teraz poprawnie importowane, i podaj link do technicznych szczegółów. Nie twierdź, że rozwiązano wszystkie błędy parsowania, jeśli zmienił się jeden przypadek.

Sprawdź aktualizację przed ogłoszeniem

Wypróbuj opisane kroki aktualizacji z obsługiwanej wcześniejszej wersji. Sprawdź linki pobierania i zgodność dokumentacji z wydaniem. Rozróżnij wersję wstępną i stabilną oraz ułatw znalezienie pozostałych ograniczeń.

Opublikuj informacje o wydaniu przed podaniem do nich linku we wpisie społecznościowym. W ogłoszeniu wyróżnij jedno ważne ulepszenie, a notatki wydania pozostaw jako szczegółowe źródło. Zbieraj dalsze pytania i w razie potrzeby doprecyzowuj instrukcje.

Częste pytania

Czy informacje o wydaniu są tym samym co dziennik zmian?

Częściowo się pokrywają. Dziennik zmian zapisuje historię, a informacje o wydaniu wyjaśniają konkretną wersję i jej wpływ na użytkowników. Połącz je linkami, aby ułatwić przechodzenie od podsumowania do szczegółów.

Czy można opublikować automatycznie wygenerowane notatki bez zmian?

Najpierw je przejrzyj. Tytuły pull requestów mogą pomijać migrację, wpływ na użytkownika lub znane problemy.

Czy każda drobna zmiana kodu powinna znaleźć się w najważniejszych zmianach?

Nie. Wyróżnij zmiany istotne dla użytkowników, a szczegółową historię techniczną zachowaj w podlinkowanym dzienniku.

Źródła