Wersje, tagi, milestones i release notes

[cameel]

Proponowane zasady

Wersje

Wersje nadajemy zgodnie z semver 2.0.

Tagi

Kod odpowiadający danej wersji tagowany jest w repozytorium gita.

• Wersje tagujemy zawsze z opcją --annotate, dzięki czemu tag ma datę, autora i opis.
• Nazwa taga składa się z wersji oraz prefiksu v, np. v0.7.3.
• Opis taga powinien zaczynać się od nazwy aplikacji i nadawanej wersji. Po nim powinny zostać podana treść release notes dla tagowanej wersji.
• Jeżeli projekt posiada osobne repozytorium deploymentowe (zawierające tylko skrypty konfigurujące serwery, klastry, kontenery, itp.), powinno być ono tagowane tymi samymi tagami co repozytorium główne.
  • Jeżeli w jednym z repozytoriów nie ma nowych zmian w momencie tagowania dopuszczalne jest zarówno nadanie ostatniemu commitowi drugiego taga jak i po prostu pominięcie w tym repozytorium tej wersji. Np. jeżeli w momencie tagowania repozytorium concent tagiem v0.7.3 w repozytorium concent-deployment ostatni commit ma już taga v0.7.2 można zarówno otagować ten commit jako v0.7.3 albo nie tagować go w ogóle.

Github releases

Github help > About Releases.

Na Githubie nadane przez nas tagi pojawiają się na liście release'ów jako zwykłe tagi.

• Aby odróżnić je od reszty tagów warto je wyedytować i zapisać przyciskiem "Publish release".
• Dodatkowo, jeżeli nie jest to produkcyjny release, zaznaczamy checkbox "This is a pre-release".
• Jeżeli repozytorium po zbudowaniu daje nam jakiś pakiet, który będzie przekazywany użytkownikom, należy ten pakiet zauploadować jako część Githubowego release'u.

Milestones

Github help > About Milestones.

Ponieważ używamy innych narzędzi do planowania iteracji, milestone'y służą nam jedynie do zapisania, które pull requesty i issues weszły do którego release'u. Ułatwia to przygotowanie release notes.

• Nazwą zamkniętego milestone'a jest wersja (bez prefiksu v).
• W danej chwili wystarczy jeden otwarty milestone o nazwie next. W momencie otagowania nowej wersji zamykamy go i zmieniamy jego nazwę na tę wersję.
• Milestone jest nadawany pull requestowi i odpowiadającemu mu issue dopiero w momencie zmerge'owania pull requesta. Nadaje go ten, kto merge'uje.
  • Pull requesty, które zostały zamknięte bez zmerge'owania nie dostają milestone'a. Zamiast tego dostają etykietę invalid.
  • Issues, które zostały zamknięte i niezrealizowane (np. zmieniła się koncepcja, bug jednak nie występuje, pull request został zamknięty bez zmerge'owania, itp.) również nie trafiają do żadnego milestone'a i dostają etykietę invalid.
  • Jeżeli issue skojarzony jest z więcej niż jednym pull requestem, trafia do tego mile'stone'a, który zawiera ostatni pull request.
  • Jeżeli pull request został zmerge'owany ale później wycofany jeszcze w tej samej wersji za pomocą git revert, trafia do milestone'a, ale dostaje jednocześnie etykietę invalid.

Relase notes

Release notes jest informacją o tym, co zmieniło się w repozytorium od ostatniej wersji i jak bezpiecznie wykonać migrację między tymi wersjami.

Jest to informacja dla użytkownika repozytorium - tzn. kogoś kto:

1. Nie jest dogłębnie zaznajomiony z developmentem i wewnątrzną strukturą projektu.
2. Będzie budował i/lub deployował kod zawarty w repozytorium.

Przygotowywanie release notes

1. Release notes przechowujemy w pliku o nazwie RELEASE-NOTES znadującym się w repozytorium lub na wiki projektu. To pierwsze ułatwia aktualizowanie go przy okazji pull requestów, to drugie zmniejsza ryzyko konfliktów.
2. W pliku znajduje się lista wszystkich wersji projektu, najnowsza wersja na górze.
3. Dla każdej wersji wymieniona jest wysokopoziomowa lista zmian. Bardzo często jeden pull request odpowiada jednej zmianie, ale nie jest to regułą. Należy pamiętać, że osoba, dla której przeznaczona jest lista nie zna drobnych szczegółów implementacyjnych. Opisy zmian powinny odwoływać się do logicznej struktury systemu przedstawionej w dokumentacji wykonawczej.
4. Dla każdej wersji powinna być podana również lista ręcznych zmian niezbędnych poczas migracji do nowej wersji:
   • Nowe ustawienia, które nie mają wartości domyślnych.
   • Ustawienia, których wartości trzeba zaktualizować.
   • Ręczne zmiany w bazie danych.
   • Jednorazowe skrypty, które powinny zostać odpalone przed włączeniem nowej wersji systemu.
   • Niekompatybilne wstecz zmiany w parametrach podawanych z linii komend.
5. Wpisy dodawane są do pliku w każdym pull requeście, który wprowadza zmiany widoczne dla użytkownika repozytorium.

[PaweuB]

Jeżeli w jednym z repozytoriów nie ma nowych zmian w momencie tagowania dopuszczalne jest zarówno nadanie ostatniemu commitowi drugiego taga jak i po prostu pominięcie w tym repozytorium tej wersji. Np. jeżeli w momencie tagowania repozytorium concent tagiem v0.7.3 w repozytorium concent-deployment ostatni commit ma już taga v0.7.2 można zarówno otagować ten commit jako v0.7.3 albo nie tagować go w ogóle.

Moim zdaniem nie powinno się zostawiać wyboru co do tagowania ostatniego commita w repozytoriach gdzie nie było zmian. Myślę, że z góry powinno się oznaczać tą samą wersją co główne/wiodące repozytorium. Myślę, że powinniśmy przyjąć jeden sposób tagowania dla aktualnego Projektu, natomiast w kolejnych ustalać workflow pod specyfikę danego projektu (taki szybki wniosek z rozmowy z Kamilem).

[cameel]

Update w kwestii revertowanych pull requestów:

• Jeżeli pull request został zmerge'owany ale później wycofany jeszcze w tej samej wersji za pomocą git revert, trafia do milestone'a, ale dostaje jednocześnie etykietę invalid.

[cameel]

Moim zdaniem nie powinno się zostawiać wyboru co do tagowania ostatniego commita w repozytoriach gdzie nie było zmian. Myślę, że z góry powinno się oznaczać tą samą wersją co główne/wiodące repozytorium. Myślę, że powinniśmy przyjąć jeden sposób tagowania dla aktualnego Projektu, natomiast w kolejnych ustalać workflow pod specyfikę danego projektu (taki szybki wniosek z rozmowy z Kamilem).

Co sądzą inni? Zostawiłem w tych kwestiach dowolność ponieważ w poprzednich projektach robiliśmy to inaczej niż w Concencie i to są akurat kwestie w których żadna z alternatyw nie wydaje mi się zła - jest to bardziej kwestia preferencji.

[Jakub89]

Moim zdaniem nie powinno się zostawiać wyboru co do tagowania ostatniego commita w repozytoriach gdzie nie było zmian. Myślę, że z góry powinno się oznaczać tą samą wersją co główne/wiodące repozytorium. Myślę, że powinniśmy przyjąć jeden sposób tagowania dla aktualnego Projektu, natomiast w kolejnych ustalać workflow pod specyfikę danego projektu (taki szybki wniosek z rozmowy z Kamilem).

Co sądzą inni? Zostawiłem w tych kwestiach dowolność ponieważ w poprzednich projektach robiliśmy to inaczej niż w Concencie i to są akurat kwestie w których żadna z alternatyw nie wydaje mi się zła - jest to bardziej kwestia preferencji.

Ja myślę, że nie powinniśmy na siłę tagować np concent-deployment tylko dlatego że wypuściliśmy nową wersje concent. Ale możemy podbijać później wersję do aktualnie najwyższej. Czyli jak zmienimy obecnego concenta z 0.9.0 na 0.9.1, ale concent-deployment zostaje na wersji 0.9.0 bo nie ma dla niego żadnych zmian. To przy kolejnym release możemy przeskoczyć z 0.9.0 na 0.9.2 w obu repo(oczywiście jeśli są jakieś zmiany dla obu).