Gitのビギナーズガイド—変更ログとは何ですか?それを生成する方法

あなたが開発者であり、プロジェクトの1つにGitを使用しているとします。行った変更をユーザーと共有したいのですが、その方法がわかりません。さて、この記事はあなたのためです。

このシリーズの最後のパートでは、適切なコミットメッセージの書き方を紹介しました。

良いコミットを書くことの利点の概要を説明し、変更ログを生成する可能性について述べました。

この記事では、変更ログとは何かを、それを生成する2つの方法(単純なものと洗練されたもの)とともに学習します。

変更ログとは何ですか?

変更ログは、プロジェクトに加えた変更の時系列のリストを共有するファイルです。多くの場合、バージョンごとに整理されており、日付の後に、追加、改善、および削除された機能のリストが続きます。

グローバルに、変更ログを作成する方法は2つあります。

  • 通常の方法:テキストファイルを作成し、特定の日付ですべての変更の列挙を開始します
  • 開発者の選択(別名レイジーオプション):コミットメッセージから変更ログを自動生成します。良いニュースがあります。これが、この記事で学習する内容です。
「変更ログは、プロジェクトに加えられたすべての注目すべき変更のログまたは記録です。プロジェクトは多くの場合、Webサイトまたはソフトウェアプロジェクトであり、変更ログには通常、バグ修正や新機能などの変更の記録が含まれています。」–ウィキペディア

なぜそれが不可欠なのですか?

今でも、なぜそれが不可欠なのか、なぜ時間をかけて作成する必要があるのか​​を自問していると思います。

変更ログは、すべての変更の要約の一種です。プロジェクトを使用しているユーザーとプロジェクトに取り組んでいる開発者の両方が理解しやすいはずです。

すべてが急速に進化している世界では、ユーザーは使用しているWebサイト/ソフトウェアが変更されているかどうかを知る必要があります。驚かれるかもしれませんが、人々はあなたのウェブサイトのブログ投稿や更新ページを読むのが大好きです。

たとえば、開発者にとって、プロジェクトが大きい場合、彼らが取り組んでいるソフトウェアがどのように進化しているかを知ることは興味深いかもしれません。

または、オープンソースプロジェクトで作業している場合は、GitHubリポジトリに「CHANGELOG.md」ファイルがあります。このファイルは、プロジェクトの最新の更新を寄稿者に通知することを目的としています。

どこにありますか?

変更ログはどこにでもあります!さて、彼らはしばしば異なるスタイルと場所を持っていますが、それらは文字通りすべてのプロジェクトにあります。

変更ログを見つけることができるいくつかの場所を含む短いリストを作成しました。

  • ブログ投稿。変更ログは、最後の機能を1つずつ共有する記事の下に配信できます。
  • GitHubリポジトリ内の「CHANGELOG.md」ファイル。
  • お気に入りのWebサイト/ソフトウェアの変更ログセクション。これは、タスク管理ツールTickTickを使用した1つの例です。
  • AndroidおよびIOSストアの「What'snew」。

変更ログの自動生成

このパートでは、最初の変更ログを一緒に生成します。

このタスクを実行することにより、いくつかのルールに従ってコミットすることが有用である理由を理解できます。

優れた明示的なコミットは変更する必要がなく、変更ログに直接追加できます。

パーソナライズや美化を行わずに必要なファイルを生成することに興味がある場合は、最初の方法をお勧めします。それ以外の場合は、2番目の方が優れています。

:Keep A Changelogなどの一部のWebサイトでは、git commitをコピーして貼り付けるだけで変更ログを作成するべきではないと説明されています(簡単な方法を参照してください)。確かに、プロの製品に取り組んでいる場合は、この方法を避けるようにすることをお勧めします。

ただし、最近では、gitログを変更ログに変更できる高度なジェネレーターがいくつかあります(高度な方法を参照してください)。

変更ログを生成する方法(簡単な方法)

この最初の方法を使用することにより、前提条件は必要ありません。必要なのは、Gitリポジトリ内にいくつかのコマンドを入力することだけです。

簡単に言うと、「git log」と入力すると、すべてのコミットのリストが表示されます。

$ 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

このコマンドは、いくつかのパラメータを取ることができます。それらを使用して出力を変更し、改善されたものを取得して変更ログを生成します。

By typing the following command, you will have an output with one commit per line.

$ 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

It’s better, but let’s see what we can do with the following one.

$ 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

With this one, you can print the list of commits with the style you want.

The “%s” corresponds to the commit title itself. You can modify the string to style your commit as you like.

In our case, we want to create a list.

$ 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

You did it! You created a simple changelog.

Note: If you want to go further, and save your changelog faster: instead of copying and pasting the result into a file, redirect it to your terminal by typing “git log --pretty="- %s" > CHANGELOG.md”

How to generate a changelog (the sophisticated way)

Prerequisites

We are now going to explore a sophisticated way to generate a changelog. The idea behind the process stays the same, but this time we’re going to use other tools to help us.

Do you remember when in the last part of this series I wrote about the Git guidelines?

Note: Git guidelines are a set of rules to write your commits better. These guidelines help you add some structure to your commits.

When you are using a guideline for your project, you can use tools to generate a changelog. Most of the time, these tools are better because they allow you to create a markdown formatted changelog.

In this example, we’re going to use a simple generator which works with most of the guidelines. Its name is “generate-changelog”, and it’s available on NPM (the Node Package Manager).

このツールは定型化された変更ログを作成しますが、ほとんどの機能を備えたツールではありません。初心者にとっては良い例なので、使うことにしました。さらに詳しく知りたい場合は、以下の変更ログツールのリストを参照してください。

使用できるツールは次のとおりです。

  • Github変更ログジェネレーター
  • Git Chglog
  • 自動変更ログ
  • 従来の変更ログ
注:ツールをインストールする前に、コンピューターにNPMをインストールする必要があります。お持ちでない場合は、公式Webサイトをフォローすることをお勧めします(NodeとNPMのインストールに役立ちます)。

コンピュータにパッケージをインストールするには、ターミナルで次のコマンドを入力します。

$ npm install generate-changelog -g 

それを行うと、インストールされます!

それを使用する方法

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.