🍺

【github】今のプロジェクト、githubをうまく活用できてるかも！？😟

2024/06/29に公開

GitHub

Slack

idea

はじめに(雑談を少し含んで🤪)

どうもこんにちは、最近一人居酒屋をデビューしたてるし〜です。
一人でカウンターでビールを飲むのもなかなか良いなと感じました😎

さてさて、現在私は業務でiosアプリのwebview部分の開発をしています。
ソース管理はgitでしておりgitを活用した開発支援ツールとしてはgithubを使用しています。

みなさんの案件ではgithubはお使いでしょうか？
「githubじゃなくてgitlabやその他のgitを活用したツールを使用しています」
といった方もいらっしゃるかもしれませんね。
はたまた、コードはgithubに載せているがissueでのタスク管理はしておらずNotionなどの別のツールを使っているといった方もいらっしゃるのではないでしょうかね。

現在、私がやっている案件では私自信が中心となってベース環境構築、githubの運用ルール等を決めました。
まだまだ試行錯誤しながらやっているのもあり課題はありますが、自分ながらうまく開発効率は上げられているのではないかな？と思いました。

なので今回はgithubで工夫したところについてをまとめてみます。

ということで今回もゆっくりしていってください！(ちょっと長くなるかもしれないです、、、)

1. issue

1.1. issueとは、そしてどう使っている？

皆さんはissueでのタスク管理をしていますか？

issueの説明を公式から丸々引用しますと、

GitHub Issues は、作業を計画、議論、追跡するためにリポジトリで作成できる項目です。

issue は簡単に作成でき、さまざまなシナリオに合わせて柔軟に対応できます。 issue を使用して、作業の追跡、フィードバックの送受信、アイデアやタスクに関する共同作業、他のユーザーとの効率的なコミュニケーションを行うことができます。

現案件では

新規機能の追加
バグの報告
リファクタリング依頼
その他のタスク(技術調査やドキュメント作成など)
などといったタスクの管理に使用しています。

issueはMarkdownベースで誰でも簡単に記述することができます。

issueを作成する際の画面は上記画像のようになりますが、実際どのような形式で書けば良いのかわからなくなることがあるかと思います。また、バラバラな形式で書かれていて読みにくく脳内がパンクしてしまう可能性もあります。
上記の問題のためにも統一されていて誰もが把握しやすい形式のissueになるようにテンプレートを作成するのが良いかと思います。

1.2. `yaml`によるissueのテンプレート

テンプレートはMarkdownファイル(.md)でも作成できますが、yamlで作るテンプレートをお勧めします。
YamadaUIやchakraUIなどはyamlでissueのテンプレートが作られています。

yamlについて詳しく方は、下記リンクをご覧ください。
https://wa3.i-3-i.info/word13801.html

issueのテンプレートを作成する手順は以下の通りです。

「プロジェクト名」/.github/ISSUE_TEMPLATEといディレクトリを作成する
その下に「ファイル名」.ymlを作成
実際にyamlを書く
コミットしてpushする

yamlコードの一例を示します。

name: "機能・ページ作成チケット"
description: "新規機能やページの作成のチケットです"
body:
  - type: textarea
    id: content
    attributes:
      label: "追加機能"
      description: "どの機能を追加するかを記載"
      placeholder: |
        〇〇の処理を作成する
    validations:
      required: true
  - type: textarea
    id: howTo
    attributes:
      label: "どのように"
      description: |
        どのような手順で作成するか
      value: |
        1. 〇〇の処理を作成
        2. 〇〇のコンポーネントを作成
        3. ページを作成
  - type: textarea
    id: issue
    attributes:
      label: "関連issue"
      description: |
        関連するissueの番号を表記してください

これをコミットすると、

という画面になります。これを使用することで形式が統一されるので書きやすくなると思います。

テンプレートを使って作成されたissueの一例も載せておきます。

1.3. その他

issueを作成する際に右側に各々の項目があると思います。これを設定しておくとより管理がしやすくなるかと思います。

Assignees
Assigneesはissueの担当者を指定しておくものです。ここは複数人選択することも可能です。

Labels
ここはラベルを指定する場所です。こちらも複数選択することができます。ラベルはデフォルトで作られているものもありますが、自身で作成、編集、削除することが可能です。ラベルをつけておくことでタスク内容がより明確にわかりやすくなるかと思っています。

Projects
ここはこのあと紹介するProjectsへの紐付け部分です。
Projectsについては次のセクションで説明します。

Milestone
ここではマイルストーンを設定できます。
本案件ではあまり使ってないですw

Development
ここはPR(PullRequest)と紐付ける場所で、マージされたら自動的にクローズされるようになります。

2. Projects

Projectsについて、こちらも引用してしまいます。

プロジェクトは、作業の計画と追跡を効果的に行えるように GitHub 上の issue および pull request と統合できる、適応性のあるスプレッドシート、タスクボード、ロードマップです。 issue と pull request をフィルター処理、並べ替え、グループ化することで複数のビューを作成してカスタマイズしたり、構成可能なグラフを使って作業を視覚化したり、team 固有のメタデータを追跡するためのカスタムフィールドを追加したりすることができます。プロジェクトには、特定の手法を適用するのではなく、チームのニーズやプロセスに合わせてカスタマイズできる柔軟な機能があります。

こちらに関しては見せられるものがないのですが、ボード上でタスクのステータスを移動してタスク管理するものです。　
下記リンクは詳しく書いていますね。

現案件では先ほどのissueと紐付けをしています。
毎朝の進捗報告会はこのProjectsを使って実施しています。

「昨日はこのタスクとこのタスクを完了し本日はこのタスクを実施いたします。...以下略」

などと、Projectsを使いながら説明することで他の人が内容把握しやすくなります。
また、誰がどのタスクをやっているのかというのもよりわかりやすくなります！

Projectsはまだまだ使いこなせてないので、使いこなしてより効率を上げていきたいところではあります。

3. Pull Request

3.1. Pull Requestについて

プロジェクトでgithubでソースコードを保管していればPull Requestは必ずやると思います。
なので説明は不要かと思いますが、主要のブランチmainやdevelopmentにマージするためのコードレビューを行う場所です。

プルリクエストを出す際に詳細を書くと思いますが、こちらもどのように書いたら良いのか、形式がバラバラだとわかりづらいなどといった問題が出てくると思います。

3.2 Pull Request　テンプレート

ということで上記問題を解決すべくテンプレートを作成しましょう。どうやらPRはyamlでは書けないのでMarkdownで書きます。

.github/pull_request_template.mdを作成します。
　中身の一例を記載します。

## issue の番号

closed #[issue の番号]

## どのような内容のタスクか

> タスクの内容をここに記載

## どんな追加・修正をしたのか(画像等を貼ってくれるとすごく助かる)

> 修正した内容を記載

## 動作検証方法

- [ ] 開発環境での実行
- [ ] 本番環境での実行
- [ ] テスト実行
- [ ] その他

> 該当するものにチェック

### より詳しく

> どのように確認して欲しいのかを記載

## 追加情報

> レビュアーに対して何かあれば

上記のコードを書いてpushするとテンプレートが出来上がりそれに沿ってPRの詳細を書くと下記画像のようになります(実際異なる部分はあります)。

3.3. issueとPRは紐付けしておく

#123

123はissueの番号になります。PRにこれを書いておくだけでissueと紐づきissueの下にリンクが出現します。

Projectsでも同じように見れるのでPRが出されているかどうか、マージされたかどうかを確認することができさらにはテスターがissueを見るときにこのissueはどのPRで実施されたのかを見ることができます。マージされたがissueをopenにしておいてテスターが確認する場合には上記のようにしておくと良いかと思います。

また、下記のように書くこともあります。

closed #123

このような記載をすると、

ここにissueの番号と内容が反映されます。
ここに反映されるとマージされてクローズされたらissueもクローズされます！

issueとPRを紐づけることでタスク管理がしやすくなると個人的には感じています！

4. discussionの活用

弊社ではコミュニティーチャットとしてslackを使っていますがソースコードについての質問、仕様の変更の連絡などをslackでやっていると後々、会話が流れていってしまうので過去のものに遡るのが大変になってしまうなと思いました。discussionを使うことで過去に誰かが質問していたな〜というような内容を見返すことができるので個人的には良いな〜と思いました。

また、議論だけでなく「共通で使うutilityの部分を作成しました〜」や「ここの部分の仕様が変更されました」
というアナウンスメント的なものも投稿しておくとslackで同じ質問をする頻度が減ります。

現案件の実際のdiscussionを見せることはできないですが、以前にYamadaUIでdiscussionを作成したことがあるのでそれを例に記載しておきます。

今回はdiscussionのテンプレートは使用してないのですが、作ることが可能みたいですね！！

5. slackでの通知

5.1. slackのチャンネルで通知をするには

githubではslackのwebhookを使い設定をすることでslackやdiscordでの通知を飛ばすことができます。
手順としては、

slackのチャンネルのwebhookを取得
github上で取得したwebhookを貼り付けてもろもろ設定をする

webhookの取得は下記リンクを参照すると良いかもです。

個人ではdiscordで紐付けをしているのですが、実際にその設定画面が以下の通りです。

slackも同様に作成されたwebhookを貼り付けてどの項目(create issuesなど)で通知するかを設定できます。

5.2. メンションをつけたい

コミュニティチャットツールで通知をしたいとなるとPRやコメント等でメンションを飛ばしたくなりますよね！
実際にその議論は案件の途中でdiscussionで議論になりました。
調べた結果、下記のようにMarkdownに記載すればメンションが飛ぶことがわかりました！

<@slackの名前>

レビュアーとしてお願いするときやレビューのコメントなどでこれはよく使うかと思います。
このようにすればいちいちslackで「レビューをお願いします」と言わずに済みますね！！！

自動化できるものは自動化したい！！！

6. wiki

6.1. wikiとは

Wiki と呼ばれるドキュメントをホストするセクションが備わっています。リポジトリのウィキは、プロジェクトの利用方法、設計方法、中核的な原理など、プロジェクトに関する長いコンテンツを共有するために利用できます。 README ファイルは、プロジェクトができることを手短に述べますが、ウィキを使えば追加のドキュメンテーションを提供できます。

仕様書を格納しているGoogleドライブのリンクや会議での議事録などをwikiで保管しておくとより便利になるなとは感じました。

6.2. 現案件での反省点

現案件ではコーディングルールやディレクトリ構成の説明等を全て/docs/*にMarkdownファイルで格納していましたがwikiを活用した方が良いかなと思いました。コーディングルールやディレクトリ構成の説明等に関してはドキュメントという分類になるのでMarkdownファイルで書くのはちょっと違うかも🧐と思いました。次の案件ではその反省点を活かしていきたいところですね😁

7. リポジトリトップ階層

ここでリポジトリのトップ階層を紹介します。
下記のようになっています。

.
├── README.md
├── CONTRIBUTION.md
├── docs・・・コーディングルール等のドキュメントを格納(今後はwikiにしようと思う)
├── production
│   ├── 案件名-webapp
│   └── 案件名-ios
└── sample・・・技術検証等に使うもの

最初の方は技術検証をするタスクが多かったのでsampleという部分で検証プロジェクトをどんどん追加していく形にしていました。
実際に納品するソースコードはproductionに格納されています。

8. ドキュメント(README等)

8.1. 参考にした記事

現案件を始めるにあたって参考にした記事があります。それは以下の記事です。

とてもわかりやすいもので納得させられるものが多かったです！

8.2. `README.md`

READMEに書いた項目は以下のものです。

プロジェクトの概要
パッケージの詳細(バージョン等)
注意事項
です。

実際のコーディングする際の環境構築等は/production/案件名-領域の中のREADMEに記載しています。
特に領域(フロントエンドやバックエンドなど)が別のディレクトリが同じリポジトリに入っている場合にはそれぞれで環境構築の仕方が違いますので。

注意事項は「このプロジェクトを始める前に」的なことを書いています。

8.3. `CONTRIBUTION.md`

このファイルではコーディングルール以外のルールを記載しています。

ブランチについて
issueについて
プルリクエストについて
レビュアーに対して
などなどです。

実際の見せられるものを下に貼っておきます。

まとめ

いかがだったでしょうか？

githubにも色々な機能があって便利だなと思うものもいくつかあったのではないでしょうか？
自身としても社会人２年目兼エンジニア2年目でまだまだ勉強不足な部分はありますが、現案件では今までの中でうまくgithubを使えていてうまくプロジェクトを回せているのではないかなと思っています。

githubだけで完結しているとあっちこっちとツールをうろうろしなくて済むのでかなり良いです。

ですが、エンジニア以外の方が参入してくるとなかなか難しい面もあるかもしれないですね！

この機能知らなかったから使ってみたい！という方は是非プロジェクトに導入してみてください！！

それではまた👋