GitHub Pagesは、GitHubにpushしたドキュメントをWebページとして公開できる便利な機能です。一般的には、gh-pages
という専用のブランチを用意して、そこにHTMLなどのドキュメントをpushして公開する場合が多いです。ただしGitHub Pages自体は、任意のブランチの任意のディレクトリを公開元として設定できます。今回は、専用ブランチを使う場合と、ソースコードと同じブランチを使う場合の、それぞれのメリットを考えてみたいと思います。
目次
gh-pagesブランチとは
GitHub Pagesの機能が登場した当初は、ドキュメント公開元にできるのはgh-pages
という名前のブランチに限られていたようです。現在では任意のブランチを使うことができるのですが、当時の名残で、今でも専用ブランチを用意する場合はgh-pages
という名前にすることが多いです。
実際の運用では、変な名前にしてしまうと、初めてそのリポジトリを見る人がドキュメントを見つけられなくなってしまいます。そういった無駄なトラブルを避けるためにも、専用ブランチならgh-pages
、ソースコードと同じブランチを使うならdocs
やdoc
などの分かりやすいディレクトリ名を使うのが良いと思います。
専用ブランチを使う方が良い場合
まずは専用ブランチgh-pages
を使うメリットを見ていきます。
ドキュメント作成を自動化する場合
GitHub Actionsと組み合わせて自動的にドキュメントを作成する場合は、専用ブランチを使うと良いです。
ライブラリのリファレンスをGitHub Pagesで公開している場合、タグのpushをトリガにGitHub Actionsのworkflowを走らせて、ドキュメントの作成と公開を自動化したりします。もしソースコードと同じブランチでドキュメントを運用すると、タグの時点ではドキュメントは古い状態になっていて、その次のコミットでドキュメントが更新されるという履歴になってしまいます。後から履歴を見たときにちょっと気持ち悪いです。
専用ブランチをorphanブランチで運用すれば、ドキュメントの履歴とソースコードの履歴が独立するので、この気持ち悪さを軽減できます。(全ブランチのコミット履歴を時系列で並べると、結局同じような違和感は見えてしまうのですが・・・)
複数のブランチで並行開発する場合
複数のブランチで開発が並行して進んでいて、ドキュメントの対象となるソースコードのブランチが頻繁に切り替わる場合も、ドキュメント専用ブランチを用意する方が良いです。ドキュメントの公開元のブランチを変更するには、GitHub Pagesの設定を変更する必要があります。専用ブランチを用意しておけば、ドキュメント公開元はいつも変わらないので、設定を変更することなく、対応可能です。
ソースコードと同じブランチを使う方がいい場合
次に、ソースコードと同じブランチの特定のディレクトリ(例えばdocs
ディレクトリなど)にドキュメントを作成して、これをGitHub Pagesの公開元とするほうがよい場合を考えてみます。
とにかく手軽に運用したい場合
手軽に運用するなら、ソースコードと同じブランチのdocs
フォルダなどにドキュメントを置くのが楽です。特に自動化とかは考えていなくて、ソースコードを書く人が、同じPCで手動でドキュメントを作る場合は、同じブランチで作業する方が楽です。複数ブランチを使い分けながら作業するのはなんだかんだ面倒です。
ソースコードとドキュメントの履歴を同列で見たい場合
「このドキュメントはいつの時点のドキュメントなの?」というのを簡単に確認できるのも、ソースコードと同じブランチでドキュメントを管理する場合のメリットです。ソースコードとドキュメントの変更履歴を同列で見ることができます。
ドキュメント更新のタイミングが厳密ではなくて、気が付いたときに更新すればいいや、くらいのゆるーい運用の場合は、「前にドキュメント更新したのいつだっけ?」ということが確認しやすい方が良さそうです。開発チーム内で共有する目的のAPIリファレンスなどは、こういった運用がありそうな気がします。
逆に、ドキュメント更新のタイミングを厳密に管理したい場合も、ソースコードの変更履歴と比較しやすいように、同じブランチ上で作業する方がいいかもしれません。
以上、GitHub Pagesのブランチ運用について考えてみました。ご自身のプロジェクトでどちらの方法を採用するか、ご参考になれば幸いです。