Git
ポエム

(ポエム)今風のソフトウェアプロジェクト構成の常識観

※ ここでいうプロジェクトは、組織の課題遂行の単位の話ではなく、GitHubにたっている何らかのプロジェクトとか、そういう単位のプロジェクトのことを言っています。有り体にいうと .git があるフォルダのことを言っています。

プロジェクトの単位

マイクロサービスであれば、マイクロサービスの単位。ほか、適当に区切りのいい単位で「プロジェクト」を作る。

普通の開発プロジェクトという総体は、複数の「プロジェクト」の成果物からなるシステムを構築・維持することになる。

プロジェクトのファイル構造

下記のように構成するのが普通。

# もはや今の時代はgitをSCMとして用いるのが標準になった
.git/
.gitignore

# いわずもがなREADME。プロジェクトの設定や開発環境の上げ方などを記載。
README.md

# プロジェクトのCI定義。ビルド → 単体テスト → パッケージング → どこかにパッケージを保管 まで一続きに記述。
# ただし、あくまでこのプロジェクト固有のCIしか扱わない。他プロジェクトとの部品の絡めは書かないのが原則。
# ビルドは「あまり環境に依存しない」で、「全自動」で行えることが大事。
Jenkinsfile, .travis.yml などなど

# もっと詳細なドキュメントがあればこちら。
/docs

# ライブラリプロジェクトの場合のライブラリ利用のサンプル
/examples

# ソース。テスト用のソースフォルダは別途あるかもしれない。
/src

# プロジェクトレベルの各種設定ファイル類
.editorconfig, .babelrc などなど

# プロジェクトの依存性記述ファイルとロックファイル
Gemfile, Gemfile.lock などなど

# ビルダースクリプト。ビルドツールインストール不要でビルドを可能にさせてくれるもの。
gradlew, mvnw, lein などなど

# プロジェクトワークスペースレベルのエディタの設定ファイル
.vscode/

# Dockerビルド定義
Dockerfile

# 即時プロジェクトを立ち上げたい人用。もっぱら私はDockerfileのビルド定義を書いている。
docker-compose.yml

# ほか必要なものがたくさんあるだろう。明示的に管理しておこう。

プロジェクトの依存性モジュールは?ビルドは?

プロジェクトの依存モジュールはちゃんとファイルなどに記述して管理される。

ビルド手順は特定マシンに依存しないように専用のファイルに記述される。

なるべくまっさらなマシンから簡単にゼロからビルド成功にたどり着けるのが理想的。

プロジェクトの成果物は?

たとえば、Javaであればjarやwarなどのパッケージ化されたバイナリがビルド成果物になるが、今の時代であればDockerイメージが一番プロジェクト成果物として利用しやすいと思う。

基本的に The Twelve-Factor Appに従って構成されており、安心してローカル→結合→検証→本番というように複数環境で同じものを使い回せるようになっている。

プロジェクト成果物の保存方法

プロジェクトの成果物はビルドがすべて成功したら(コンパイル、ビルド、バンドルなどが成功したら)、バージョン番号が付与され下記のようなアーティファクトリポジトリに収められることになっている。(別に必須ではない。)

プロジェクトの成果物を使って環境を構築する時は、上記のリポジトリから直接成果物を持ってくるように構成することとなる。

プロジェクトのバージョニング

何も指針がなければ、セマンティックバージョニングを用いればよい。

複数プロジェクトを組み合わせている場合は、複数プロジェクト間で統一した番号を用いるとかのほうがわかりやすいこともある。

プロジェクト開発環境

  • Slackのような近代的なチャット
  • GitHubやGitLabなどのWeb画面付きの近代的なSCM
  • CI。最近のはDocker特化型が多い。
  • アーティファクトリポジトリ(上記に書いた)
  • ITS。RedmineやJIRAなどの課題追跡システム。
  • (LDAP。いろいろな開発環境のプロジェクトメンバ定義は一括で管理できると楽。)
  • 頻繁にデプロイでき、結合検証、本番前検証できるサーバやクラスタ、クラウド環境

git リポジトリの用い方

以下のフローか、もしくはもっとシンプルにするとかで複数人ないし一人が並列して開発できるように配慮する。

  • git-flow
  • GitHub Flow

そもそも複数人並列で開発するのは、無料ではできない話で、採用しているソフトウェアアーキテクチャが複数人並列開発に寛容じゃなければ、上記のフローを用いたところでまったく役に立たない。

おわりに

このエントリに書いたようなことは、今の時代であれば、特に話題にされることがない常識だと思うが、その常識が掴みきれずに空回りしてしまう人も多いと思い、書いた。

つまり、自分のために書いた。

あとはプロジェクトメンバーを巻き込んで、SCRUMをやったり〜などと書きたいところだが、そっち方面は全然かけそうにないので、やめる。