Dodawanie informacji o zmianach do informacji o wydaniu¶
Wiele narzędzi BeeWare wykorzystuje
towncrier do pomocy w tworzeniu
informacji o wydaniu dla każdej wersji. Kiedy wysyłasz pull request do jednego z
odpowiednich narzędzi, musi on zawierać informację o zmianie — ta informacja
stanie się wpisem w informacjach o wydaniu opisującym wprowadzoną zmianę.
Każde żądanie pull musi zawierać co najmniej jeden plik w katalogu changes/,
zawierający krótki opis zmiany wprowadzonej przez żądanie pull. Informacja o
zmianie powinna być w formacie Markdown, w pliku o nazwie w formacie
<id>.<fragment type>.md. Jeśli proponowana zmiana naprawia błąd lub wprowadza
funkcję, dla której istnieje numer zgłoszenia, identyfikatorem będzie numer tego
zgłoszenia. Jeśli zmiana nie ma odpowiadającego jej zgłoszenia, jako
identyfikator można użyć numeru PR. Numer PR będzie znany dopiero po przesłaniu
pull requestu, więc pierwsze przejście CI zakończy się niepowodzeniem
sprawdzenia towncrier; dodaj notatkę dotyczącą zmiany i prześlij aktualizację
PR, a CI powinno przejść pomyślnie.
Istnieje pięć typów fragmentów:
feature: PR dodaje nowe zachowanie lub funkcję, które wcześniej nie były możliwe (np. dodanie obsługi nowego formatu pakietów lub nowej funkcji w istniejącym formacie pakietów);bugfix: PR naprawia błąd w istniejącej implementacji;doc: PR stanowi znaczną poprawę dokumentacji;doc: PR stanowi znaczną poprawę dokumentacji;misc; Niewielka lub administracyjna zmiana (np. poprawienie literówki, niewielkie wyjaśnienie językowe lub aktualizacja wersji zależności), która nie wymaga ogłoszenia w informacjach o wydaniu.
Opis w notatce dotyczącej zmian powinien być ogólnym podsumowaniem zmian z punktu widzenia użytkownika, a nie szczegółowym opisem technicznym lub szczegółami wdrożenia. Różni się on od komunikatu zatwierdzenia — komunikat zatwierdzenia opisuje, co zostało zrobione, aby przyszli programiści mogli zrozumieć powody wprowadzenia zmian; notatka dotycząca zmian jest opisem przeznaczonym dla użytkowników, którzy mogą nie mieć wiedzy na temat wewnętrznych aspektów.
Na przykład, jeśli naprawisz błąd związany z nazewnictwem projektu, komunikat zatwierdzenia może brzmieć:
Zastosuj silniejsze sprawdzanie wyrażeń regularnych, aby uniemożliwić stosowanie nazw projektów zaczynających się od cyfr.
Odpowiednia informacja o zmianie brzmiałaby mniej więcej tak:
Nazwy projektów nie mogą już zaczynać się od cyfry.
Niektóre PR wprowadzają wiele funkcji i naprawiają wiele błędów lub wprowadzają wiele zmian niezgodnych wstecznie. W takim przypadku PR może zawierać wiele plików z informacjami o zmianach. Jeśli chcesz powiązać dwa typy fragmentów z tym samym identyfikatorem, możesz dodać numeryczny sufiks. Na przykład, jeśli PR 789 dodał funkcję opisaną w zgłoszeniu 123, zamknął błąd opisany w zgłoszeniu 234, a także wprowadził dwie zmiany niezgodne wstecznie, możesz mieć 4 pliki z informacjami o zmianach:
123.feature.md234.bugfix.md789.removal.1.md789.removal.2.md
Więcej informacji na temat towncrier i typów fragmentów można znaleźć w sekcji
Fragmenty
wiadomości.
Istniejące przykłady fragmentów wiadomości można również znaleźć w katalogu
changes repozytorium BeeWare. Jeśli ten folder jest pusty,
prawdopodobnie wynika to z faktu, że BeeWare opublikowało niedawno
nową wersję; pliki z informacjami o zmianach są usuwane i łączone w celu
aktualizacji informacji o wydaniu wraz z każdym wydaniem. Możesz zapoznać się z tym plikiem, aby
zobaczyć wymagany styl komentarzy; możesz również przejrzeć ostatnio scalone
PR-y, aby zobaczyć, jak sformatować swoje informacje
o zmianach.