Ein Anfängerleitfaden für Git - Was ist ein Changelog und wie man ihn generiert

Angenommen, Sie sind Entwickler und verwenden Git für eines Ihrer Projekte. Sie möchten die vorgenommenen Änderungen mit Ihren Benutzern teilen, wissen aber nicht, wie. Dann ist dieser Artikel genau das Richtige für Sie.

Im letzten Teil dieser Serie habe ich Ihnen erklärt, wie Sie eine gute Commit-Nachricht schreiben.

Ich gab Ihnen einen Überblick über die Vorteile des Schreibens eines guten Commits und erwähnte die Möglichkeit, ein Änderungsprotokoll zu erstellen.

In diesem Artikel erfahren Sie, was ein Changelog ist und wie Sie es auf zwei Arten generieren können - ein einfaches und ein anspruchsvolles.

Was ist ein Changelog?

Ein Änderungsprotokoll ist eine Datei, die eine chronologisch geordnete Liste der Änderungen enthält, die Sie an Ihrem Projekt vorgenommen haben. Es wird häufig nach der Version mit dem Datum gefolgt von einer Liste der hinzugefügten, verbesserten und entfernten Funktionen organisiert.

Weltweit gibt es zwei Möglichkeiten, ein Änderungsprotokoll zu schreiben:

  • Der übliche Weg: Erstellen Sie eine Textdatei und beginnen Sie, alle Ihre Änderungen mit einem bestimmten Datum aufzulisten
  • Die Entwicklerauswahl (alias die Lazy-Option): Generieren Sie Ihr Änderungsprotokoll automatisch aus Ihren Commit-Nachrichten. Ich habe gute Nachrichten für Sie - das werden Sie in diesem Artikel lernen!
„Ein Änderungsprotokoll ist ein Protokoll oder eine Aufzeichnung aller wichtigen Änderungen, die an einem Projekt vorgenommen wurden. Das Projekt ist häufig eine Website oder ein Softwareprojekt, und das Änderungsprotokoll enthält normalerweise Aufzeichnungen über Änderungen wie Fehlerkorrekturen, neue Funktionen usw. “ - Wikipedia

Warum ist es wichtig?

Ich denke, auch jetzt fragen Sie sich, warum es wichtig ist und warum Sie sich die Zeit nehmen sollten, es zu erstellen.

Ein Änderungsprotokoll ist eine Art Zusammenfassung aller Ihrer Änderungen. Es sollte sowohl für die Benutzer, die Ihr Projekt verwenden, als auch für die Entwickler, die daran arbeiten, leicht verständlich sein.

In einer Welt, in der sich alles schnell entwickelt, muss ein Benutzer wissen, ob sich die von ihm verwendete Website / Software ändert. Sie werden vielleicht überrascht sein, aber die Leute lesen gerne Blog-Beiträge oder eine Update-Seite auf Ihrer Website.

Wenn ein Entwickler beispielsweise ein großes Projekt hat, kann es interessant sein zu wissen, wie sich die Software entwickelt, an der er arbeitet.

Wenn Sie an einem Open-Source-Projekt arbeiten, finden Sie eine Datei "CHANGELOG.md" im GitHub-Repository. Diese Datei soll die Mitwirkenden über die neuesten Aktualisierungen des Projekts informieren.

Wo finden wir sie?

Changelogs sind überall! Okay, sie haben oft unterschiedliche Stile und Orte, aber sie sind buchstäblich bei jedem Projekt dabei.

Ich habe eine kurze Liste mit einigen Stellen erstellt, an denen Sie ein Änderungsprotokoll finden können.

  • Ein Blogbeitrag. Ein Änderungsprotokoll kann unter einem Artikel geliefert werden, der Punkt für Punkt die letzten Funktionen teilt.
  • Eine "CHANGELOG.md" -Datei in einem GitHub-Repository.
  • Ein Changelog-Bereich auf Ihrer bevorzugten Website / Software. Hier ist ein Beispiel mit dem Task-Management-Tool TickTick.
  • In "Was ist neu" auf dem Android und dem IOS Store.

Changelog Auto-Generation

In diesem Teil erstellen wir gemeinsam unser erstes Änderungsprotokoll.

Wenn Sie diese Aufgabe ausführen, werden Sie verstehen, warum es nützlich sein kann, ein Commit durchzuführen, indem Sie einige Regeln befolgen.

Ein ausgezeichnetes und explizites Commit muss nicht geändert werden und kann direkt zum Änderungsprotokoll hinzugefügt werden.

Wenn Sie daran interessiert sind, eine erforderliche Datei ohne Personalisierung oder Verschönerung zu erstellen, empfehle ich den ersten Weg. Ansonsten ist der zweite besser.

Hinweis : Einige Websites wie Keep A Changelog erklären, dass Sie ein Änderungsprotokoll nicht nur durch Kopieren und Einfügen Ihrer Git-Commits erstellen sollten (siehe einfache Methode). In der Tat empfehle ich, diesen Weg zu vermeiden, wenn Sie an einem professionellen Produkt arbeiten.

Heutzutage gibt es jedoch einige erweiterte Generatoren, mit denen Sie Ihre Git-Protokolle in Änderungsprotokolle ändern können (siehe die ausgefeilte Methode).

So erstellen Sie ein Changelog (auf einfache Weise)

Wenn Sie diesen ersten Weg verwenden, benötigen Sie keine Voraussetzungen. Sie müssen lediglich einige Befehle in Ihr Git-Repository eingeben.

Zur einfachen Erinnerung: Wenn Sie "git log" eingeben, wird eine Liste aller Ihrer Commits angezeigt.

$ git log // Output commit f6986f8e52c1f889c8649ec75c5abac003102999 (HEAD -> master, origin/master, origin/HEAD) Author: Sam Katakouzinos  Date: Tue Mar 10 11:41:18 2020 +1100 docs(developers): commit message format typo Any line of the commit message cannot be longer *than* 100 characters! Closes #17006 commit ff963de73ab8913bce27a1e75ac01f53e8ece1d9 Author: Chives  Date: Thu Feb 6 19:05:57 2020 -0500 docs($aria): get the docs working for the service Closes #16945 commit 2b28c540ad7ebf4a9c3a6f108a9cb5b673d3712d Author: comet  Date: Mon Jan 27 19:49:55 2020 -0600 docs(*): fix spelling errors Closes #16942

Dieser Befehl kann einige Parameter annehmen. Wir werden sie verwenden, um die Ausgabe zu ändern und eine verbesserte zu erhalten, um unser Änderungsprotokoll zu generieren.

Wenn Sie den folgenden Befehl eingeben, erhalten Sie eine Ausgabe mit einem Commit pro Zeile.

$ git log --oneline --decorate // Output f6986f8e5 (HEAD -> master, origin/master, origin/HEAD) docs(developers): commit message format typo ff963de73 docs($aria): get the docs working for the service 2b28c540a docs(*): fix spelling errors 68701efb9 chore(*): fix serving of URI-encoded files on code.angularjs.org c8a6e8450 chore(package): fix scripts for latest Node 10.x on Windows 0cd592f49 docs(angular.errorHandlingConfig): fix typo (wether --> whether) a4daf1f76 docs(angular.copy): fix `getter`/`setter` formatting be6a6d80e chore(*): update copyright year to 2020 36f17c926 docs: add mention to changelog ff5f782b2 docs: add mention to changelog 27460db1d docs: release notes for 1.7.9 add78e620 fix(angular.merge): do not merge __proto__ property

Es ist besser, aber mal sehen, was wir mit dem folgenden machen können.

$ git log --pretty=”%s” // Output docs(developers): commit message format typo docs($aria): get the docs working for the service docs(*): fix spelling errors chore(*): fix serving of URI-encoded files on code.angularjs.org chore(package): fix scripts for latest Node 10.x on Windows docs(angular.errorHandlingConfig): fix typo (wether --> whether) docs(angular.copy): fix `getter`/`setter` formatting chore(*): update copyright year to 2020 docs: add mention to changelog docs: add mention to changelog docs: release notes for 1.7.9 fix(angular.merge): do not merge __proto__ property

Mit diesem können Sie die Liste der Commits mit dem gewünschten Stil drucken.

Das "% s" entspricht dem Commit-Titel selbst. Sie können die Zeichenfolge so ändern, dass Ihr Commit nach Ihren Wünschen gestaltet wird.

In unserem Fall möchten wir eine Liste erstellen.

$ git log --pretty="- %s" // Output - docs(developers): commit message format typo - docs($aria): get the docs working for the service - docs(*): fix spelling errors - chore(*): fix serving of URI-encoded files on code.angularjs.org - chore(package): fix scripts for latest Node 10.x on Windows - docs(angular.errorHandlingConfig): fix typo (wether --> whether) - docs(angular.copy): fix `getter`/`setter` formatting - chore(*): update copyright year to 2020 - docs: add mention to changelog - docs: add mention to changelog - docs: release notes for 1.7.9 - fix(angular.merge): do not merge __proto__ property

Du hast es geschafft! Sie haben ein einfaches Änderungsprotokoll erstellt.

Hinweis : Wenn Sie weiter gehen und Ihr Änderungsprotokoll schneller speichern möchten: Anstatt das Ergebnis zu kopieren und in eine Datei einzufügen, leiten Sie es an Ihr Terminal um, indem Sie "git log --pretty =" -% s "> CHANGELOG.md" eingeben.

So erstellen Sie ein Changelog (auf raffinierte Weise)

Voraussetzungen

Wir werden nun einen ausgeklügelten Weg untersuchen, um ein Änderungsprotokoll zu erstellen. Die Idee hinter dem Prozess bleibt dieselbe, aber dieses Mal werden wir andere Tools verwenden, um uns zu helfen.

Erinnerst du dich, als ich im letzten Teil dieser Serie über die Git-Richtlinien schrieb?

Hinweis : Git-Richtlinien sind eine Reihe von Regeln, mit denen Sie Ihre Commits besser schreiben können. Diese Richtlinien helfen Ihnen dabei, Ihren Commits eine gewisse Struktur zu verleihen.

Wenn Sie eine Richtlinie für Ihr Projekt verwenden, können Sie mithilfe von Tools ein Änderungsprotokoll erstellen. In den meisten Fällen sind diese Tools besser, da Sie damit ein Änderungsprotokoll im Markdown-Format erstellen können.

In diesem Beispiel verwenden wir einen einfachen Generator, der mit den meisten Richtlinien funktioniert. Der Name lautet "generate-changelog" und ist auf NPM (dem Node Package Manager) verfügbar.

Dieses Tool erstellt ein stilisiertes Änderungsprotokoll, ist jedoch nicht das mit den meisten Funktionen. Ich habe mich für es entschieden, weil es ein hervorragendes Beispiel für einen Anfänger ist. Wenn Sie weiter gehen möchten, lesen Sie bitte die Liste der Änderungsprotokoll-Tools unten:

Hier sind einige Tools, die Sie verwenden können:

  • Github Changelog Generator
  • Git Chglog
  • Auto Changelog
  • Konventionelles Changelog
Hinweis: Vor der Installation des Tools muss NPM auf Ihrem Computer installiert sein. Wenn Sie es nicht haben, lade ich Sie ein, der offiziellen Website zu folgen (es wird Ihnen helfen, Node und NPM zu installieren).

Geben Sie den folgenden Befehl in Ihr Terminal ein, um das Paket auf Ihrem Computer zu installieren.

$ npm install generate-changelog -g 

Sobald Sie das tun, ist es installiert!

Wie man es benutzt

To make this package work, you need to follow the guidelines for using this pattern – “type(category): description [flags]”. In this example, I will use the Angular.js GitHub repository.

Now you can type the generate command in your terminal inside your GitHub repository.

$ changelog generate

A “CHANGELOG.md” file will be automatically created and filled with your logs in a markdown format.

You can find an example of the output (with a markdown reader such as GitHub) below.

Conclusion

I hope you liked this guide and now understand how to create a changelog for your project. I think it’s a good way to demonstrate why you should write good commit messages.

Feel free to try other changelog generators and send me the result!

If you have any questions or feedback, please let me know.

Don't miss my content by following me on Twitter and Instagram.

You can find other articles like this on my website: herewecode.io.

Want more?

  • Each week get a motivational quote with some advice, a short tutorial in a few slides, and one developer's picture on Instagram.
  • Sign-up for the newsletter and get the latest articles, courses, tutorials, tips, books, motivation, and other exclusive content.