Konwencje dziennika zmian
Konwencje dziennika zmian
Dział zatytułowany „Konwencje dziennika zmian”Ta strona definiuje kontrakt, którego każde publiczne repozytorium NextPDF przestrzega przy rejestrowaniu zmian i publikowaniu wydań. To dokumentacja referencyjna konwencji; nie określa zachowania pakietów. Informacje o wydaniach dla poszczególnych pakietów i wersji znajdują się w pliku CHANGELOG.md danego repozytorium. Te wspólne reguły utrzymują podsumowanie międzyrepozytoryjnego dziennika zmian w spójnej formie, wolnej od wycieków.
Conventional Commits 1.0.0
Dział zatytułowany „Conventional Commits 1.0.0”Tytuł każdego commita ma postać type(scope): description. Wartość type jest jedną z następujących:
| Typ | Znaczenie | Widoczne dla użytkownika | Wpływ na wersję |
|---|---|---|---|
feat | Nowa funkcjonalność | tak | podniesienie wersji minor |
fix | Poprawka zachowania | tak | podniesienie wersji patch |
perf | Poprawa wydajności bez zmiany zachowania | tak | podniesienie wersji patch |
refactor | Wewnętrzna przebudowa bez obserwowalnych zmian | nie | brak |
docs | Tylko dokumentacja | nie | brak |
test | Tylko testy | nie | brak |
build / ci | Tylko proces budowania lub potok CI | nie | brak |
chore | Konserwacja, zależności lub narzędzia | nie | brak |
revert | Wycofanie wcześniejszego commita | zależnie | zależnie |
Zmianę łamiącą zgodność oznacza znak ! po typie lub zakresie (feat(api)!: …) albo stopka BREAKING CHANGE:. Każdy z tych znaczników wymusza podniesienie wersji major zgodnie z Semantic Versioning. Poprawkę istotną dla bezpieczeństwa odnotuj tak, aby mogła pojawić się w kolumnie Security międzyrepozytoryjnego podsumowania.
Semantic Versioning 2.0.0
Dział zatytułowany „Semantic Versioning 2.0.0”Podnoszenie wersji jest mechaniczne. Wydanie zawierające jakąkolwiek zmianę łamiącą zgodność jest wydaniem major. W przeciwnym razie wydanie zawierające dowolny feat jest wydaniem minor. W przeciwnym razie wydanie zawierające dowolny fix lub perf jest wydaniem patch. W przypadku pakietów sprzed wersji 1.0 zmiana łamiąca zgodność może oznaczać podniesienie wersji minor, zgodnie z SemVer §4. Commit nadal zawiera znacznik zmiany łamiącej zgodność, aby podsumowanie pozostawało dokładne.
Grupowanie według Keep a Changelog
Dział zatytułowany „Grupowanie według Keep a Changelog”Plik CHANGELOG.md każdego repozytorium jest zgodny z Keep a Changelog 1.1.0: wpisy są grupowane według wydanych wersji w kategoriach Added, Changed, Deprecated, Removed, Fixed oraz Security. Sekcja [Unreleased] może zawierać w repozytorium notatki dotyczące prac w toku, ale międzyrepozytoryjne podsumowanie uwzględnia wyłącznie wersje oznaczone tagiem i wydane. Niewydane prace nigdy nie pojawiają się w publicznym indeksie.
Jak powstaje międzyrepozytoryjne podsumowanie (i jak pozostaje wolne od wycieków)
Dział zatytułowany „Jak powstaje międzyrepozytoryjne podsumowanie (i jak pozostaje wolne od wycieków)”Tabela podsumowania na stronie indeksu dziennika zmian powstaje przez odczytanie w trybie tylko do odczytu historii Conventional Commits każdego repozytorium dla jego najnowszego wydanego tagu oraz zliczenie kategorii. Reguły wyprowadzania danych są celowo wąskie, aby wewnętrzne szczegóły nie wydostały się na zewnątrz:
- Liczby, nie treść. Raportowana jest wyłącznie liczba commitów każdego typu widocznego dla użytkownika. Nie są wyświetlane żadne tytuły, treści, stopki ani skróty (hash) commitów.
- Tylko typy widoczne dla użytkownika.
docs,test,ci,choreorazrefactorsą wykluczone, ponieważ nie zmieniają niczego, co obserwuje konsument pakietu. - Tylko wydane. Commit jest liczony dopiero wtedy, gdy stanie się częścią oznaczonego tagiem wydania publicznego pakietu.
- Brak identyfikatorów. Wewnętrzne odwołania do zgłoszeń, ticketów, cykli, fal lub elementów pracy, które mogą pojawić się w prywatnym zakresie commita, nigdy nie są ujawniane, ponieważ tekst zakresu nigdy nie jest wyświetlany. Odczytywany jest wyłącznie typ.
- Brak atrybucji automatyzacji. Stopki automatyzacji przypisujące współtwórców nie są odczytywane ani wyświetlane.
Z tego powodu publiczny dziennik zmian jest podsumowaniem kategorii z odnośnikami do pliku CHANGELOG.md właściwego pakietu, a nie zagregowanym strumieniem commitów. Podsumowanie jest z założenia wolne od wycieków informacji wewnętrznych. Wiążący opis wydania pozostaje przy pakiecie, którego dotyczy.