Korzystam z Git od jakiegoś czasu, a ostatnio zacząłem używać go do oznaczania swoich wydań, aby móc łatwiej śledzić zmiany i zobaczyć, która wersja jest uruchomiona przez każdego z naszych klientów (niestety kod obecnie nakazuje że każdy klient ma własną kopię strony PHP; Zmieniam to, ale jest powolna).

W każdym razie zaczynamy nabierać rozpędu. Pomyślałem, że dobrze byłoby pokazać ludziom, co się zmieniło od ostatniego wydania. Problem polega na tym, że nie prowadziłem dziennika zmian, ponieważ nie mam pojęcia, jak sobie z tym poradzić. W tym konkretnym czasie mogę uruchomić dziennik i ręcznie go utworzyć, ale to bardzo szybko się męczy.

Próbowałem googlingu „git changelog” i „git manage changelog”, ale nie znalazłem niczego, co naprawdę mówiłoby o przepływie zmian w kodzie i tym, jak to się pokrywa z dziennikiem zmian. Obecnie śledzimy przebieg prac rozwojowych Reina Henrichsa i bardzo bym chciał, aby coś takiego się stało.

Czy brakuje mi standardowego podejścia, czy jest to dziedzina, w której każdy robi swoje?

Bardzo dziękuję za komentarze i odpowiedzi!

Było to około 3-4 lata temu, ale ze względu na przyszłych poszukiwaczy możliwe jest teraz generowanie wspaniałych dzienników za pomocą:

git log --oneline --decorate

Lub, jeśli chcesz, aby był jeszcze ładniejszy (z kolorem dla terminala):

git log --oneline --decorate --color

Przesyłanie tego wyjścia do ChangeLog jest obecnie tym, czego używam we wszystkich moich projektach, jest po prostu niesamowite.

Możesz użyć jakiegoś smaku dziennika git, aby ci pomóc:

git log --pretty=%s                 # only print the subject

Jeśli ładnie nazywasz swoje gałęzie, aby scalenie do opanowania pojawiło się jako coś w rodzaju „Fobar połączonej gałęzi”, możesz skrócić rzeczy, pokazując tylko tę wiadomość, a nie wszystkie małe zmiany, które scaliłeś, które razem tworzą funkcja:

git log --pretty=%s --first-parent  # only follow first parent of merges

Być może będziesz w stanie rozszerzyć to za pomocą własnego skryptu, który może na przykład usuwać bity „Scalonej gałęzi”, normalizować formatowanie itp. W pewnym momencie oczywiście musisz to napisać sam.

Następnie możesz utworzyć nową sekcję dla dziennika zmian raz dla każdej wersji:

git log [opts] vX.X.X..vX.X.Y | helper-script > changelogs/X.X.Y

i zatwierdzić to w swojej wersji zatwierdzić wydanie.

Jeśli Twoim problemem jest to, że podmioty zatwierdzające nie przypominają tego, co chciałbyś umieścić w dzienniku zmian, masz prawie dwie opcje: rób wszystko ręcznie (i staraj się nadążyć za nim częściej niż grać w catch- w momencie wydania) lub napraw styl komunikatu zatwierdzenia. Jedną opcją, jeśli badani nie zamierzają tego zrobić dla ciebie, byłoby umieszczenie wierszy typu „zmień: dodany foobar funkcji” w treści wiadomości zatwierdzających, abyś później mógł zrobić coś takiego, git log --pretty=%B | grep ^change:aby złapać tylko te super ważne bity wiadomości.

Nie jestem do końca pewien, o ile więcej niż ten git może naprawdę pomóc w tworzeniu dzienników zmian. Może źle zrozumiałem, co rozumiesz przez „zarządzać”?

ZASTRZEŻENIE: Jestem autorem gitchangelog, o którym będę mówić poniżej.

TL; DR: Może chcesz sprawdzić własny dziennik zmian gitchangeloga lub wyjście ascii, które wygenerowało poprzednie.

Jeśli chcesz wygenerować dziennik zmian z historii git, prawdopodobnie będziesz musiał rozważyć:

• format . (Czysty niestandardowy ASCII, typ dziennika zmian Debiana, Markdow, ReST ...)
• niektóre filtrowanie zmian (prawdopodobnie nie chcesz widzieć wszystkich literówek lub kosmetycznych zmian w dzienniku zmian)
• niektóre zatwierdzają tekst przed włączeniem do dziennika zmian. (Zapewnienie normalizacji wiadomości jako zawierających pierwszą literę lub ostatnią kropkę, ale może to również oznaczać usunięcie specjalnych znaczników w podsumowaniu)
• czy twoja historia git jest kompatybilna ? Łączenie, tagowanie nie zawsze jest tak łatwo obsługiwane przez większość narzędzi. To zależy od tego, jak zarządzasz swoją historią.

Opcjonalnie możesz potrzebować jakiejś kategoryzacji (nowe rzeczy, zmiany, poprawki błędów) ...

Mając to na uwadze, stworzyłem i używam gitchangelog . Ma to na celu wykorzystanie konwencji komunikatów git commit do osiągnięcia wszystkich poprzednich celów.

Posiadanie konwencji zatwierdzania jest obowiązkowe, aby utworzyć fajny dziennik zmian (z użyciem lub bez gitchangelog).

zatwierdzenie konwencji wiadomości

Poniżej znajdują się sugestie, co może być przydatne, aby pomyśleć o dodawaniu wiadomości zatwierdzania.

Możesz z grubsza podzielić swoje zobowiązania na duże sekcje:

• według zamiaru (na przykład: nowy, napraw, zmień ...)
• według obiektu (na przykład: dokument, opakowanie, kod ...)
• według odbiorców (na przykład: deweloper, tester, użytkownicy ...)

Dodatkowo możesz chcieć oznaczyć niektóre zatwierdzenia:

• jako „niewielkie” zatwierdzenia, które nie powinny być wypisywane do Twojego dziennika zmian (zmiany kosmetyczne, mała literówka w komentarzach ...)
• jako „refaktoryzator”, jeśli tak naprawdę nie ma znaczących zmian funkcji. Dlatego nie powinno to również stanowić części dziennika zmian wyświetlanego na przykład użytkownikowi końcowemu, ale może być interesujące, jeśli masz dziennik zmian dla programistów.
• możesz oznaczyć również „api”, aby zaznaczyć zmiany interfejsu API lub nowe elementy interfejsu API ...
• ...itp...

Spróbuj napisać komunikat zatwierdzenia, kierując reklamy do użytkowników (funkcjonalność) tak często, jak to możliwe.

przykład

Jest to standard git log --onelinepokazujący, jak te informacje mogą być przechowywane:

* 5a39f73 fix: encoding issues with non-ascii chars.
* a60d77a new: pkg: added ``.travis.yml`` for automated tests. 
* 57129ba new: much greater performance on big repository by issuing only one shell command for all the commits. (fixes #7)
* 6b4b267 chg: dev: refactored out the formatting characters from GIT.
* 197b069 new: dev: reverse ``natural`` order to get reverse chronological order by default. !refactor 
* 6b891bc new: add utf-8 encoding declaration !minor 

Jeśli więc zauważyłeś, wybrałem format:

{new|chg|fix}: [{dev|pkg}:] COMMIT_MESSAGE [!{minor|refactor} ... ]

Aby zobaczyć rzeczywisty wynik wyjściowy, możesz spojrzeć na koniec strony PyPI gitchangelog

Aby zobaczyć pełną dokumentację mojej konwencji komunikatów zatwierdzania, możesz zobaczyć plik referencyjny gitchangelog.rc.reference

Jak wygenerować z tego znakomity dziennik zmian

Wówczas całkiem łatwo jest stworzyć kompletny dziennik zmian. Możesz zrobić własny skrypt dość szybko lub użyć gitchangelog.

gitchangelogwygeneruje pełny changelog (ze skrawków jako wsparcie New, Fix...), i jest rozsądnie konfigurować do własnych konwencji popełniających. Obsługuje wszelkiego rodzaju wyjściowych dzięki templating przez Mustache, Mako templatingi ma domyślną starszego napisany w Pythonie surowego; wszystkie obecne 3 silniki mają przykłady ich użycia i mogą wyświetlać dziennik zmian, jak ten wyświetlany na stronie PyPI w gitchangelogu.

Jestem pewien, że wiesz, że istnieje wiele innych git logdo changelognarzędzi tam również.

Bardziej do rzeczy CHANGELOG. Powiedz mi, jeśli ci się spodoba.

git log --since=1/11/2011 --until=28/11/2011 --no-merges --format=%B

gitlog-to-changelogSkrypt jest przydatna do wygenerowania GNU stylu ChangeLog.

Jak pokazuje gitlog-to-changelog --help, możesz wybrać zatwierdzenia użyte do wygenerowania ChangeLogpliku, korzystając z jednej z opcji --since:

gitlog-to-changelog --since=2008-01-01 > ChangeLog

lub przekazując dodatkowe argumenty później --, które zostaną przekazane git-log(wywołane wewnętrznie przez gitlog-to-changelog):

gitlog-to-changelog -- -n 5 foo > last-5-commits-to-branch-foo

Na przykład używam następującej reguły na najwyższym poziomie Makefile.amjednego z moich projektów:

.PHONY: update-ChangeLog
update-ChangeLog:
    if test -d $(srcdir)/.git; then                         \
       $(srcdir)/build-aux/gitlog-to-changelog              \
          --format='%s%n%n%b%n' --no-cluster                \
          --strip-tab --strip-cherry-pick                   \
          -- $$(cat $(srcdir)/.last-cl-gen)..               \
        >ChangeLog.tmp                                      \
      && git rev-list -n 1 HEAD >.last-cl-gen.tmp           \
      && (echo; cat $(srcdir)/ChangeLog) >>ChangeLog.tmp    \
      && mv -f ChangeLog.tmp $(srcdir)/ChangeLog            \
      && mv -f .last-cl-gen.tmp $(srcdir)/.last-cl-gen      \
      && rm -f ChangeLog.tmp;                               \
    fi

EXTRA_DIST += .last-cl-gen

Ta reguła jest używana w momencie wydania do aktualizacji ChangeLognajnowszymi, jeszcze nie nagranymi komunikatami zatwierdzenia. Plik .last-cl-genzawiera identyfikator SHA1 najnowszego zatwierdzenia zapisanego w ChangeLogi jest przechowywany w repozytorium Git. ChangeLogjest również zapisywany w repozytorium, dzięki czemu można go edytować (np. w celu poprawienia literówek) bez zmiany komunikatów zatwierdzania.

Ponieważ tworzenie tagów dla poszczególnych wersji jest najlepszą praktyką, możesz podzielić dziennik zmian na partycje według wersji. W takim przypadku to polecenie może ci pomóc:

git log YOUR_LAST_VERSION_TAG..HEAD --no-merges --format=%B

Dla projektach GitHub może się przydać: github-changelog-generator

Generuje dziennik zmian na podstawie zamkniętych tagów i połączonych żądań ściągania.

To CHANGELOG.md został wygenerowany przez ten skrypt.

Przykład:

Dziennik zmian

1.2.5 (2015-01-15)

Pełna lista zmian

Wdrożone ulepszenia:

• Użyj kamienia milowego, aby określić, w której wersji błąd został naprawiony # 22

Naprawione błędy:

• Błąd podczas próby wygenerowania dziennika dla repozytorium bez tagów # 32

Połączone żądania ściągnięcia:

• Do klasy PrettyPrint dołączono małe litery „pp” # 43 ( schwing )

• obsługa github dla przedsiębiorstw za pomocą opcji wiersza poleceń # 42 ( glenlovett )

Zrobiłem też bibliotekę do tego. Jest w pełni konfigurowalny z szablonem Wąsy. To może:

• Przechowywać w pliku, np. CHANGELOG.md . .
• Opublikuj na MediaWiki
• Lub po prostu wydrukuj do STDOUT

Wykonałem również:

• Wtyczki Gradle
• Plugin Maven
• Wtyczki Jenkins
• Wtyczki Bitbucket Server
• Narzędzie wiersza poleceń

Więcej informacji na temat Github: https://github.com/tomasbjerre/git-changelog-lib

Z linii poleceń:

npx git-changelog-command-line -std -tec "
# Changelog

Changelog for {{ownerName}} {{repoName}}.

{{#tags}}
## {{name}}
 {{#issues}}
  {{#hasIssue}}
   {{#hasLink}}
### {{name}} [{{issue}}]({{link}}) {{title}} {{#hasIssueType}} *{{issueType}}* {{/hasIssueType}} {{#hasLabels}} {{#labels}} *{{.}}* {{/labels}} {{/hasLabels}}
   {{/hasLink}}
   {{^hasLink}}
### {{name}} {{issue}} {{title}} {{#hasIssueType}} *{{issueType}}* {{/hasIssueType}} {{#hasLabels}} {{#labels}} *{{.}}* {{/labels}} {{/hasLabels}}
   {{/hasLink}}
  {{/hasIssue}}
  {{^hasIssue}}
### {{name}}
  {{/hasIssue}}

  {{#commits}}
**{{{messageTitle}}}**

{{#messageBodyItems}}
 * {{.}} 
{{/messageBodyItems}}

[{{hash}}](https://github.com/{{ownerName}}/{{repoName}}/commit/{{hash}}) {{authorName}} *{{commitTime}}*

  {{/commits}}

 {{/issues}}
{{/tags}}
"

Lub w Jenkins:

git log --oneline --no-merges `git describe --abbrev=0 --tags`..HEAD | cut -c 9- | sort

To jest to, co lubię używać. Pobiera wszystkie zatwierdzenia od ostatniego tagu. cutpozbywa się skrótu zatwierdzenia. Jeśli użyjesz numerów biletów na początku wiadomości zatwierdzenia, zostaną one pogrupowane według sort. Sortowanie również pomaga, jeśli prefiks niektóre z zobowiązuje fix, typoitp

Zezwalam serwerowi CI przesyłać następujące elementy do pliku o nazwie CHANGELOGdla każdego nowego wydania z datą ustawioną w nazwie pliku wydania:

>git log --graph --all --date=relative --pretty=format:"%x09 %ad %d %s (%aN)"

Dla dziennika zmian w stylu GNU przygotowałem tę funkcję

gnuc() {
  {
    printf "$(date "+%Y-%m-%d")  John Doe  <[email protected]>\n\n"
    git diff-tree --no-commit-id --name-only -r HEAD | sed 's/^/\t* /'
  } | tee /dev/tty | xsel -b
}

Z tym:

• Okresowo zatwierdzam moje zmiany w celu utworzenia kopii zapasowej i zmiany ich podstawy przed ostateczną edycją dziennika zmian
• następnie uruchomić: gnuc

a teraz mój schowek zawiera coś takiego:

2015-07-24  John Doe  <[email protected]>

        * gdb/python/py-linetable.c (): .
        * gdb/python/py-symtab.c (): .

Następnie używam schowka jako punktu początkowego do aktualizacji ChangeLog.

Nie jest doskonały (np. Pliki powinny być względne do ścieżki ChangeLog, więc python/py-symtab.cbez, gdb/ponieważ będę edytować gdb/ChangeLog), ale jest dobrym punktem wyjścia.

Bardziej zaawansowane skrypty:

• https://github.com/tromey/git-gnu-changelog przez Tromey, opiekun GDB
• GCC contrib / mklog
• https://github.com/davidmalcolm/gcc-refactoring-scripts/blob/1fc7fe038bffbb2b48d0a7a300625639f01aefa1/generate-changelog.py

Muszę jednak zgodzić się z Tromeyem: powielanie danych git commit w dzienniku zmian jest bezużyteczne.

Jeśli masz zamiar zrobić dziennik zmian, zrób z niego dobre podsumowanie tego, co się dzieje, możliwie jak podano na stronie http://keepachangelog.com/

Na podstawie bithavoc , to wymienia last tagaż HEAD. Mam jednak nadzieję, że wymienię dzienniki między 2 tagami.

// 2 or 3 dots between `YOUR_LAST_VERSION_TAG` and `HEAD`
git log YOUR_LAST_VERSION_TAG..HEAD --no-merges --format=%B

Wyświetl dzienniki między 2 tagami.

// 2 or 3 dots between 2 tags
git log FROM_TAG...TO_TAG

Na przykład wyświetli dzienniki od v1.0.0do v1.0.1.

git log v1.0.0...v1.0.1 --oneline --decorate