はじめに
現在、多くの開発のバージョン管理ツールとしてGitが利用されるようになりました。
その中でも特に多くの開発で利用されているサービスと言えばGitHub 。
この記事ではチーム開発を加速させるオススメ機能を7つ厳選してご紹介致します。
対象読者
- GitHubを用いてチームで開発・運営を行っている方
- GitHubをうまく活用してコミュニケーションを円滑にしたいと考えている方
お品書き
- Issues/PullRequestテンプレート機能
- コードオーナーの設定と自動マージ
- Draft pull Request機能
- コードハイライト機能
- Diff機能(ブランチ、タグ、コミット)
- GitHub Grep機能(高度検索機能)
- ブランチタイムライン表示機能
1. Issues/PullRequestテンプレート機能
IssuesやPullRequest作成時に文面をテンプレート文章を自動的に挿入します。
【メリット】
- 記載内容の統一し、コミュニケーションロス低減
- 過去のIssueのコピペ・編集の手間の削減
【デメリット】
記載粒度が細かいと形骸化する。
Issuesテンプレートの作成方法
Settingタブから実施要領は以下の通りです。
（※リポジトリ設定権限がない場合は後述の「Settingタブが表示されない場合(リポジトリの設定権限がない場合）」を参照ください）
1.1.1 GitHubのSettingタブを表示
1.1.2 Features - Issuesより「Set up templates」を選択
1.1.3 テンプレートを選択と編集
テンプレートは以下3種類から選択することができます。
1. Bugテンプレート(バグ用テンプレート)
2. Featureテンプレート(機能リクエストテンプレート)
3. カスタムテンプレート(空のテンプレート）
追加したテンプレートは画面上でカスタマイズすることも可能です。
1.1.4 テンプレートをコミットする
「Propose changes」ボタンより追加したテンプレートをコミットすることができます。
オプションとして、以下2種類を選択することができるので、プロジェクトの方針に合わせて選択しましょう。
1. デフォルトブランチへ直接コミット
2. 別ブランチを作成しプルリクエストを作成する
コミットされると以下のディレクトリにmdファイルが追加されます
repo/.github/ISSUE_TEMPLATE/
1.1.5 Issuesからテンプレートを選択します
Issuesから「New issue」をクリックすると追加したテンプレートが表示されます。
Settingタブが表示されない場合(リポジトリの設定権限がない場合）
直接以下のディレクトリへファイルを作成しPushしても同様の効果を得ることができます。フォーマットは以下の通り。
---
name: タイトル
about: フォーマットについての説明
title: 'タイトルのPrefix'
labels: ラベル
assignees: アサイン
---
# テンプレート本文(Markdownで記載)
Ex.) 質問用のIssueテンプレートを追加したい場合
---
name: Question
about: Ask the developer about the feature
title: '[Question]'
labels: question
assignees: ''
---
# テンプレート本文(Markdownで記載)
repo/.github/ISSUE_TEMPLATE/questions.mdを追加すると、Issuesに追加した内容が追加されていることがわかります。
Pull Requstテンプレートの作成方法
Pull Requstのテンプレートは直接ファイルレポジトリへファイルを追加する形となります。
ファイルの配置先は以下の通りとなります。
repo/.github/PULL_REQUEST_TEMPLATE.md (デフォルトのテンプレートファイル)
repo/.github/PULL_REQUEST_TEMPLATE/[任意の名前].md
ファイルの追加方法( デフォルトテンプレートの場合 )
テンプレートの追加
プルリクエストへの反映
本設定はGitHub上の画面から実施しましたが、ローカルで編集してPushする方法でもOKです。
任意テンプレートの追加方法と利用方法
利用用途
本機能を利用する場合は用途・運用を事前に検討ください。
- 機能追加、バグでテンプレートを分けたい
- masterブランチやstagingブランチへのマージでテンプレートを分けたい
設定方法
プロジェクトルールを運用を検討する必要があります。以下はmasterブランチマージする時のPull Requestは別のテンプレートを利用する。
.githubディレクトリにPULL_REQUEST_TEMPLATEを作成し、任意の名前のmdファイルを作成します。
Pull Request時のパラメータに&template=[テンプレートファイル名]を入れることで適用されます。
コピペ用テンプレート
先程作ったテンプレートの通りとなります。プロジェクトに合わせてカスタマイズしてご利用ください。
**対処概要**
～ 対処内容を簡潔に明記する ～
**対処内容**
～ 対処内容を明記する ～
**関連チケット**
～ 関連するissue / pull request を明記する ～
**関連資料**
～ 設計書のパス(URL）を明記する
**チェックリスト**
- [ ] タイトルは簡潔か
- [ ] コーディングガイドラインに遵守しているか
- [ ] フォーマッタは実行しているか
- [ ] 静的解析にて潜在バグを指摘されていないか
- [ ] 単体試験はパスしているか
- [ ] 疎通確認は実施しているか
**特記事項**
**証跡**
尚、上記で配置する方法の他にPull Requestテンプレート( PULL_REQUEST_TEMPLATE.md )は以下ディレクトリへの配置も許容しております。Pull Requestのテンプレートは一つでOKという場合は以下に配置しましょう。
| 場所 | ファイル名 |
|---|---|
| リポジトリ直下 | repo/PULL_REQUEST_TEMPLATE.md |
| docs/配下 | repo/docs/PULL_REQUEST_TEMPLATE.md |
2. コードオーナーの設定と自動マージ
本章ではブランチへのマージ事故を回避すると共に、開発に待ち時間を作らないために用意されているGitHubの機能について紹介致します。
【機能内容】
- デフォルトブランチの変更
- ブランチへの直接のPush禁止
- コードオーナー設定
- 自動的にマージする機能（現在ベータ版）
【メリット】
- マージ事故の防止
- レビューの徹底。コード品質の保証
- 待ち時間の軽減
2.1. デフォルトブランチの変更
repository新規作成時、defaultブランチは masterとなります。(※)
masterブランチへ誤って操作をされるのを防止するため、developブランチをデフォルトブランチにします。
※2020年10月にmasterをmainブランチにするという発表 がありましたが本記事ではmasterという名称で記載します。
Settings -> Branches -> Default branch
2.2. ブランチへの直接Push禁止
リリース後ソースコードやE2E試験環境のソースコードが入っているブランチへ直接Pushされると、管理者の知らないところでコード改変が行われてしまい、品質を担保することが難しくなります。本例ではmasterブランチに直接Pushすることを禁止とする設定を行います( プロジェクトによって stagingやdevelopブランチへのpushも制限も検討しましょう。)
2.2.1 直接Push禁止設定
ここではmasterブランチを対象に最小限の設定のみかけます。プロジェクトに応じて設定項目を見直ししましょう。
Settings -> Branches -> Branch protection rules -> Add rule
| 設定項目 | 設定内容 |
|---|---|
| Branch name pattern | 制限をかけたいブランチ名を指定します(正規表現利用可) |
| Protect matching branches | Pull Requestを強制する( これで直接Pushされることはなくなります) |
| Include administrators | 管理者にも適用する |
2.2.1. 直接Push禁止設定
Rejectの確認
Reviewを必須となっていることの確認
2.3. コードオーナーの設定
先程の設定では誰かが承認するとMerge可能となってしまいます。そのため必須レビューアの設定を行います
2.3.1. コードオーナーの設定を有効にする
- Settings -> Branches -> Branch protection rule -> 対象ルールを選択
- Protect matching branches に 「Require review from Code Owners」にチェックを入れる
2.3.2. CODEOWNERSファイルを作成する
リポジトリ直下にCODEOWNERSファイルを作成する
レビューアを細かく分ける場合
monorepo運用を行っている場合やプログラミング言語によってレビューアを変更したいというケースがあるかと思います。
| 設定例 | 対象内容 |
|---|---|
| * | 全ファイル対象 |
| *.js | 拡張子による制限 |
| /dir | ROOT配下にあるdirディレクトリにある全てのファイル |
| dir/ | dirディレクトリ名配下にある全てのファイル |
| dir/* | dirディレクトリ名配下の第一階層のファイル |
詳細は公式ドキュメントをご連絡ください。
https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/about-code-owners
コードオーナーのレビューが必須であることの確認
鍵穴マークが表示されていること
「Code owner review required」と表示されていること
2.3. 自動マージの設定(ベータ版)
必須レビューアがApproveしたら即座にMergeする設定をいれ、マージ漏れや待ち時間を減らします。
2.3.1. 自動マージの有効化
Settings -> Merge button -> Allow auto-merge へチェックをつける
2.3.2. プロテクトされたブランチへのPull Requestを出す
Enable auto-mergeと表示されていること。auto-merge有効後、必須レビューアによるレビューにてApproveされたら自動マージされます
3. Draft pull Request機能
作業中のPull Requestの作成します。
メリット
- 進捗状況の見える化
- 有識者によるウォークスルーレビューによる手戻り工数の低減
- Merge事故防止( Draft pull requestではMerge不可 )
3.1. 「Create pull request」ボタンの右にある「▼」より「Create draft pull request」へ変更し、ボタンを押下する
3.2. 「Ready for review」で正式のPull Requestへ昇格させる
4. コードハイライト機能
Gitのテキストファイルを行単位でハイライトします。
メリット
コミュニケーションの円滑化( ファイル名、クラス名、関数名、行番号を伝える工数を削減 )
4.1. 構文
[1行]
https://github.com/[owner]/[repo]/blob/[branch]/**filepath**/#L行番号
[複数]
https://github.com/[owner]/[repo]/blob/[branch]/**filepath**/#L行番号-#L行番号
5. Diff機能(ブランチ、タグ、コミット)
ブランチ間やTag間、またはコミット間の差分を表示します。
メリット
- コミュニケーションの円滑化と工数削減
5.1. 構文
[ブランチ間で比較する]
https://github.com/[owner]/[repo]/compare/[branch]...[branch]
[Tag間で比較する]
https://github.com/[owner]/[repo]/compare/[tag]...[tag]
[Commit間で比較する]
https://github.com/[owner]/[repo]/compare/[commit hash]...[commit hash]
「ブランチとタグ」「タグとコミット」などの組み合わせも可能です
例)タグ間での可視化
Spring Frameworkのv5.3.1とv5.3.2を比較
https://github.com/spring-projects/spring-framework/compare/v5.3.1...v5.3.2
6. GitHub Grep機能(高度検索機能)
GitHubの対象リポジトリのソースコードを検索したい時、わざわざcloneしたり、zipでダウンロードする必要はございません。
対象リポジトリ内で完結してソースコードを検索することが出来ます。
メリット
- 検索の手間軽減
- コミュニケーションの円滑化(URLだけで連携できるのは嬉しい)
6.1. 検索ページを開く
https://github.com/search/advanced
入力項目
特定のリポジトリ内を検索する場合以下を設定すること
| 設定項目 | 対象内容 |
|---|---|
| In these repositories | owners/repository |
例）spring frameworkからRestTemplateという単語を検索する
検索結果
該当のリポジトリの情報が検索されます。動作を見たい方は以下のURLで実際に結果をご確認ください。
https://github.com/search?l=&q=RestTemplate+repo%3Aspring-projects%2Fspring-framework+language%3AJava&type=code
今回は最小限の設定のみ記載しましたがAdvanced searchには様々条件を指定できますので色々と試してみましょう。
6.2. URLにて直接検索を行う
毎回advanced searchページを開くのは大変なのでURLを直接変更して検索を行います。
構文
&q=[検索ワード]
上記を直接編集することで、好きなワードで検索が行えます。
7. ブランチタイムライン表示機能
自身が作業しているブランチがどのブランチから派生したのか？またはいつマージされたのか？グラフィカルに表示する。
メリット
- ブランチ状況把握にかかる工数削減
リポジトリのコミットはマージ状況の可視化する
Insights -> Network
番外編：ダークモード
ダークモードラブ！という方GitHubにもちゃんとダークモードが用意されました！
ダークモードを有効化する(ベータ版)
さいごに
いかがでしたでしょうか？
普段から利用されている機能もあれば、知らなかった機能もあるのではないでしょうか？
各プロジェクトによってバージョン管理の運用は様々かと思っております。
運用するための手順書を作成することも大切ですが、システム側で制限を付与することによって未然の事故防止や手順の簡略化ができるのではないかと思っております。使えそうな機能がありましたら、今後の業務にお役立てください。
最後まで読んでいただきましてありがとうございました。
改訂履歴
2021/1/11
PULL_REQUEST_TEMPLATE.mdのコピペ用テンプレートから「区分」を削除しました。Pull Requstを出す際はlabelで運用を行うようにしましょう ( @ucan-lab 様ご指摘ありがとうございます！ )