Gute Möglichkeiten, ein Changelog mit Git zu verwalten?

214

Ich benutze Git jetzt schon eine Weile und habe kürzlich damit begonnen, meine Releases zu markieren, damit ich Änderungen leichter verfolgen und sehen kann, welche Version jeder unserer Clients ausführt (leider schreibt der Code derzeit dies vor dass jeder Client seine eigene Kopie der PHP-Site hat (ich ändere dies, aber es geht nur langsam voran).

Auf jeden Fall fangen wir an, etwas Schwung zu gewinnen. Ich dachte, es wäre wirklich gut, den Leuten zeigen zu können, was sich seit der letzten Veröffentlichung geändert hat. Das Problem ist, dass ich kein Änderungsprotokoll geführt habe, weil ich keine gute Vorstellung davon habe, wie ich vorgehen soll. Für diese bestimmte Zeit kann ich das Protokoll durchgehen und manuell eines erstellen, aber das wird sehr schnell anstrengend.

Ich habe versucht, "git changelog" und "git manage changelog" zu googeln, aber ich habe nichts gefunden, was wirklich über den Workflow von Codeänderungen und darüber, wie dies mit dem Changelog übereinstimmt, gesprochen hat. Wir verfolgen derzeit den Entwicklungsworkflow von Rein Henrichs und ich würde etwas lieben, das damit einhergeht.

Gibt es einen Standardansatz, den ich vermisse, oder ist dies ein Bereich, in dem jeder sein eigenes Ding macht?

Vielen Dank für Ihre Kommentare / Antworten!

Topher Fangio
quelle

Antworten:

181

Dies war vor ungefähr 3-4 Jahren, aber für zukünftige Suchende ist es jetzt möglich, wunderschöne Protokolle zu erstellen mit:

git log --oneline --decorate

Oder, wenn Sie es noch schöner wollen (mit Farbe für Terminal):

git log --oneline --decorate --color

Das Weiterleiten dieser Ausgabe an ChangeLog ist das, was ich derzeit in all meinen Projekten verwende. Es ist einfach erstaunlich.


quelle
4
Ein weiteres nützliches Tag ist --graph, das Ihnen visuell anzeigt, in welchen Zweigen sich die Commits befinden.
Eruant
44
Ich würde dringend davon abraten, Geschenkprotokollunterschiede als CHANGELOG zu verwenden: keepachangelog.com
Olivier Lacan
4
Das Kopieren der git logAusgabe in das Änderungsprotokoll hat keinen Sinn. Sie müssen filtern und bearbeiten, um ein lesbares Änderungsprotokoll zu erhalten. Warum benötigen Sie sonst überhaupt ein Änderungsprotokoll? Ich denke, Sie können die Erstellung eines Änderungsprotokolls automatisieren, aber bitte machen Sie keine Rohkopie davon git log!
Vaab
19
Das Problem dabei ist, dass Sie, selbst wenn jeder Mitwirkende an Ihrem Projekt klare und lesbare Commit-Nachrichten schreibt, immer noch ein "Changelog" erstellen, das Tonnen von Rauschen enthält. Änderungsprotokolle sollten mit dem Ziel geschrieben werden, den Benutzern Ihres Projekts die für sie relevanten bemerkenswerten Änderungen zu erklären, die zwischen den Releases aufgetreten sind, während sich Commit-Nachrichten darauf konzentrieren sollten, Entwicklern zu erklären, welche Verbesserungen Ihr Commit am Code vornimmt . Manchmal gibt es dort Überschneidungen, aber nicht immer.
Ajedi32
7
Um dies etwas konkreter zu gestalten, erstellt diese Methode ein "Änderungsprotokoll" mit vielen Einträgen wie "Feste Schreibweise von fooMethod in ZModule" und "Refactor XModule zur Verwendung einer neuen Version von XYLibarary". Ihre Benutzer interessieren sich nicht dafür . Sie möchten wissen, welche Änderungen aus ihrer Sicht als Benutzer vorgenommen wurden, nicht aus Ihrer Sicht als Entwickler. Und das ignoriert sogar Dinge wie "Merge PR # 123 von xdev / foo" und "Opps, NewFeature behoben, damit es tatsächlich funktioniert", die wahrscheinlich in einem realen Repo existieren.
Ajedi32
60

Sie können eine Variante von Git Log verwenden, um Ihnen zu helfen:

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

Wenn Sie Ihre Zweige gut benennen, so dass eine Zusammenführung zum Master als "Zusammengeführte Zweig-Feature-Foobar" angezeigt wird, können Sie die Dinge verkürzen, indem Sie nur diese Nachricht anzeigen und nicht alle kleinen Commits, die Sie zusammengeführt haben und die zusammen das bilden Feature:

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

Möglicherweise können Sie dies mit einem eigenen Skript ergänzen, mit dem Sie beispielsweise die "Zusammengeführten Verzweigungs" -Bits entfernen, die Formatierung normalisieren usw. Irgendwann müssen Sie es natürlich selbst schreiben.

Dann können Sie einmal pro Version einen neuen Abschnitt für das Änderungsprotokoll erstellen:

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

und schreiben Sie das in Ihrer Version fest.

Wenn Ihr Problem darin besteht, dass diese Festschreibungsthemen nicht mit dem übereinstimmen, was Sie in ein Änderungsprotokoll aufnehmen möchten, haben Sie so ziemlich zwei Möglichkeiten: Machen Sie alles manuell (und versuchen Sie, regelmäßig damit Schritt zu halten, anstatt Catch zu spielen). zum Zeitpunkt der Veröffentlichung) oder korrigieren Sie Ihren Commit-Nachrichtenstil. Eine Option, wenn die Betreffs dies nicht für Sie tun, besteht darin, Zeilen wie "Ändern: Feature-Foobar hinzufügen" in die Textkörper Ihrer Festschreibungsnachrichten einzufügen, damit Sie später so etwas wie git log --pretty=%B | grep ^change:nur diese Super- Nachrichten abrufen können -wichtige Bits der Nachrichten.

Ich bin mir nicht ganz sicher, wie viel mehr als dieser Git dir wirklich helfen könnte, deine Changelogs zu erstellen. Vielleicht habe ich falsch interpretiert, was Sie unter "verwalten" verstehen?

Cascabel
quelle
2
Das ist definitiv ein guter Anfang, und ich hatte nicht daran gedacht, dem Körper einen Modifikator hinzuzufügen, damit ich ihn später erfassen kann. Das ist vielleicht das, was ich am Ende mache. Danke für die Rückmeldung! Wenn am nächsten Tag keine weiteren Antworten eingehen, werde ich Ihre als Antwort markieren :-)
Topher Fangio
60

HAFTUNGSAUSSCHLUSS: Ich bin der Autor von gitchangelog, von dem ich im Folgenden sprechen werde.

TL; DR: Möglicherweise möchten Sie das eigene Änderungsprotokoll von gitchangelog oder die ASCII-Ausgabe überprüfen , die das vorherige generiert hat.

Wenn Sie ein Änderungsprotokoll aus Ihrem Git-Verlauf erstellen möchten, müssen Sie wahrscheinlich Folgendes berücksichtigen:

  • das Ausgabeformat . (Reines benutzerdefiniertes ASCII, Debian-Changelog-Typ, Markdow, ReST ...)
  • Einige Commit-Filter (Sie möchten wahrscheinlich nicht alle Tippfehler oder kosmetischen Änderungen in Ihrem Changelog sehen).
  • Einige schreiben Text, bevor sie in das Änderungsprotokoll aufgenommen werden. (Sicherstellen, dass Nachrichten so normalisiert werden, dass sie einen Großbuchstaben oder einen letzten Punkt haben, aber möglicherweise auch ein spezielles Markup in der Zusammenfassung entfernt werden.)
  • Ist dein Git-Verlauf kompatibel ? Das Zusammenführen und Markieren wird von den meisten Tools nicht immer so einfach unterstützt. Dies hängt davon ab, wie Sie Ihren Verlauf verwalten.

Optional möchten Sie vielleicht eine Kategorisierung (neue Dinge, Änderungen, Bugfixes) ...

Vor diesem Hintergrund habe ich Gitchangelog erstellt und verwendet . Es soll eine Git-Commit-Nachrichtenkonvention nutzen , um alle vorherigen Ziele zu erreichen.

Eine Konvention für Festschreibungsnachrichten ist obligatorisch, um ein schönes Änderungsprotokoll zu erstellen (mit oder ohne Verwendung gitchangelog).

Commit-Nachrichtenkonvention

Im Folgenden finden Sie Vorschläge, wie Sie Ihre Commit-Nachrichten hinzufügen können.

Möglicherweise möchten Sie Ihre Commits grob in große Abschnitte unterteilen:

  • absichtlich (zum Beispiel: neu, reparieren, ändern ...)
  • nach Objekt (zum Beispiel: Dokument, Verpackung, Code ...)
  • nach Publikum (zum Beispiel: Entwickler, Tester, Benutzer ...)

Darüber hinaus möchten Sie möglicherweise einige Commits markieren:

  • als "kleinere" Commits, die nicht in Ihr Changelog ausgegeben werden sollten (kosmetische Änderungen, kleiner Tippfehler in Kommentaren ...)
  • als "Refactor", wenn Sie keine wesentlichen Funktionsänderungen haben. Daher sollte dies nicht auch Teil des Änderungsprotokolls sein, das beispielsweise dem Endbenutzer angezeigt wird, sondern kann von Interesse sein, wenn Sie ein Entwickler-Änderungsprotokoll haben.
  • Sie können auch mit "api" markieren, um API-Änderungen oder neue API-Inhalte zu markieren ...
  • ...etc...

Versuchen Sie, Ihre Commit-Nachricht zu schreiben, indem Sie Benutzer (Funktionen) so oft wie möglich ansprechen.

Beispiel

Dies ist Standard, um git log --onelinezu zeigen, wie diese Informationen gespeichert werden können ::

* 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 

Wenn Sie es bemerkt haben, habe ich folgendes Format gewählt:

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

Um ein tatsächliches Ausgabeergebnis zu sehen, können Sie sich das Ende der PyPI-Seite von gitchangelog ansehen

Eine vollständige Dokumentation meiner Commit-Nachrichtenkonvention finden Sie in der Referenzdatei gitchangelog.rc.reference

Wie man daraus ein exquisites Änderungsprotokoll generiert

Dann ist es ganz einfach, ein vollständiges Änderungsprotokoll zu erstellen. Sie können Ihr eigenes Skript ziemlich schnell erstellen oder verwendengitchangelog .

gitchangeloggeneriert ein vollständiges Änderungsprotokoll (mit Schnittunterstützung als New, Fix...) und kann angemessen nach Ihren eigenen Festschreibungskonventionen konfiguriert werden. Es unterstützt jede Art von Leistung durch Templating durch Mustache, Mako templatingund verfügt über eine Standard - Legacy - Engine in rohem Python geschrieben; Alle aktuellen 3 Engines haben Beispiele für ihre Verwendung und können Änderungsprotokolle ausgeben, wie sie auf der PyPI-Seite von gitchangelog angezeigt werden.

Ich bin sicher , Sie wissen, dass es viele andere sind git logzu changelogauch Tools gibt.

Vaab
quelle
1
Das ist großartig, genau das, wonach ich gesucht habe. Ich werde das ausprobieren, vielen Dank!
Jeff Kiiza
26

Ein mehr auf den Punkt CHANGELOG. Sag mir, ob es euch gefällt.

git log --since=1/11/2011 --until=28/11/2011 --no-merges --format=%B
Harshniket Seta
quelle
Dies macht es irgendwie: Ich würde andere Parameter hinzufügen --format, wie in git-scm.com/docs/git-log#_pretty_formats
bluesmonk
23

Das gitlog-to-changelogSkript ist praktisch, um einen GNU-Stil zu generieren ChangeLog.

Wie von gezeigt gitlog-to-changelog --help, können Sie die zum Generieren einer ChangeLogDatei verwendeten Commits mit einer der folgenden Optionen auswählen --since:

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

oder indem Sie nachher zusätzliche Argumente übergeben --, die an git-log(intern aufgerufen von gitlog-to-changelog) übergeben werden:

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

Zum Beispiel verwende ich die folgende Regel in der obersten Ebene Makefile.ameines meiner Projekte:

.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

Diese Regel wird zum Zeitpunkt der Veröffentlichung verwendet, um ChangeLogmit den neuesten noch nicht aufgezeichneten Festschreibungsnachrichten zu aktualisieren . Die Datei .last-cl-genenthält die SHA1-Kennung des zuletzt festgeschriebenen Commits ChangeLogund wird im Git-Repository gespeichert. ChangeLogwird auch im Repository aufgezeichnet, so dass es bearbeitet werden kann (z. B. um Tippfehler zu korrigieren), ohne die Festschreibungsnachrichten zu ändern.

Roland Levillain
quelle
Das GCC-Mklog-Skript kann auch interessant sein: stackoverflow.com/a/31606865/895245
Ciro Santilli 法轮功 冠状 病 六四 事件 24
Dies sollte das Gewinnerprojekt sein! Warum hast du es nicht auf Github?
Omer Dagan
20

Da das Erstellen eines Tags pro Version die beste Vorgehensweise ist, möchten Sie möglicherweise Ihr Änderungsprotokoll pro Version partitionieren. In diesem Fall kann dieser Befehl Ihnen helfen:

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

Für GitHub- Projekte kann es nützlich sein: github-changelog-generator

Es generiert ein Änderungsprotokoll aus geschlossenen Tags-Tags und zusammengeführten Pull-Anforderungen.

Dieser CHANGELOG.md wurde von diesem Skript generiert.

Beispiel:

Änderungsprotokoll

1.2.5 (2015-01-15)

Voller Changelog

Implementierte Verbesserungen:

  • Verwenden Sie den Meilenstein, um anzugeben, in welcher Version der Fehler # 22 behoben wurde

Behobene Fehler:

  • Fehler beim Versuch, ein Protokoll für das Repo ohne Tags # 32 zu erstellen

Zusammengeführte Pull-Anforderungen:

  • Die PrettyPrint-Klasse ist in Kleinbuchstaben 'pp' # 43 ( schwing ) enthalten.

  • Unterstützen Sie Enterprise Github über die Befehlszeilenoptionen # 42 ( glenlovett )

Skywinder
quelle
Solche Projekte sind die besten :) Was war Ihre Motivation dafür? Dank Ihrer Inspiration habe ich auch ein ähnliches Tool erstellt, das ohne Beschriftungen funktioniert, in Added / Changed / Fixed / Removed aufgeteilt wird und in PHP (meiner "Muttersprache") vorliegt : github.com/Symplify/ChangelogLinker Schreiben Sie Beiträge über Changlogs? ? Ich würde sie gerne lesen
Tomáš Votruba
1
@ TomášVotruba danke für die herzlichen Worte. Es ist nur mein Hobby. Ich habe nicht viel gepostet. Aber ich denke es lohnt sich. Die besten Wünsche!
Skywinder
10

Ich habe auch eine Bibliothek dafür gemacht. Es ist vollständig mit einer Moustache-Vorlage konfigurierbar. Das kann:

  • In einer Datei wie CHANGELOG.md gespeichert werden .
  • Gepostet werden an MediaWiki
  • Oder einfach auf STDOUT gedruckt werden

Ich habe auch gemacht:

Weitere Details zu Github: https://github.com/tomasbjerre/git-changelog-lib

Über die Befehlszeile:

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}}
"

Oder in Jenkins:

Geben Sie hier die Bildbeschreibung ein

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

Ist das, was ich gerne benutze. Es werden alle Commits seit dem letzten Tag abgerufen. cutwird den Commit-Hash los. Wenn Sie zu Beginn Ihrer Festschreibungsnachrichten Ticketnummern verwenden, werden diese mit gruppiert sort. Sortierung hilft auch , wenn Sie bestimmte Commits Präfix mit fix, typoetc.

Orkoden
quelle
3

Ich habe den CI-Server Folgendes in eine Datei leiten lassen, die CHANGELOGfür jede neue Version mit dem im Release-Dateinamen festgelegten Datum benannt ist:

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

Für ein Änderungsprotokoll im GNU-Stil habe ich die Funktion gekocht

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
}

Mit diesem:

  • Ich übergebe meine Änderungen regelmäßig zum Sichern und erneuten Basieren, bevor ich das ChangeLog endgültig bearbeite
  • dann renne: gnuc

und jetzt enthält meine Zwischenablage so etwas wie:

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

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

Dann verwende ich die Zwischenablage als Ausgangspunkt, um das ChangeLog zu aktualisieren.

Es ist nicht perfekt (z. B. sollten Dateien relativ zu ihrem ChangeLog-Pfad sein, also python/py-symtab.cohne, gdb/da ich das bearbeiten werde gdb/ChangeLog), aber es ist ein guter Ausgangspunkt.

Fortgeschrittenere Skripte:

Ich muss Tromey jedoch zustimmen: Das Duplizieren von Git-Commit-Daten im ChangeLog ist nutzlos.

Wenn Sie ein Änderungsprotokoll erstellen möchten, geben Sie eine gute Zusammenfassung der Vorgänge, möglicherweise wie unter http://keepachangelog.com/ angegeben.

Ciro Santilli 郝海东 冠状 病 六四 事件 法轮功
quelle
2

Basierend auf bithavoc , listet es die last tagbis HEAD. Aber ich hoffe, die Protokolle zwischen 2 Tags aufzulisten.

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

Listen Sie Protokolle zwischen 2 Tags auf.

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

Beispielsweise werden Protokolle von v1.0.0bis aufgelistet v1.0.1.

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

AechoLiu
quelle