Edited at

ユル~く使うGitLab(ギットラボ)<Issue,MRテンプレート化計画編>


はじめに

非常に高機能なGtLabを使う上で大事な、「どういう風に使うのか」をまとめていくシリーズです。

ざっくりと概要をまとめた記事がこちら

ノンプログラマの同志へ向けた、GitLabのススメ

同シリーズの記事がこちら(随時追加予定)

ユル~く使うGitLab(ギットラボ)<リポジトリ運用編>

本記事ではこれまでの記事内でも触れた、「Issue(イシュー)、Merge Request(マージリクエスト 以下MR)のテンプレート化」について書いていきます。

内容としては「Issue,MRの活用方法」と「Issue,MRをテンプレート化する方法」の二本立てです。

GitLabはソースコードそれ自体というより、プロジェクト全体を管理、共有するのに有効なツールです。

それどころか、複数人で開発をするという状況ではいっそコミュニケーションツールといってもいいかも……という機能までもっています。

とはいえ、いきなりそれを使いこなすのも難しい話。

そもそも、そんな機能を使うのはガチなエンジニアの人たちだけ……自分とは関係ない……と考えている方もいるのでは?

本記事はGitLabの多機能さ、自由さに困惑した人たちの、まず最初の指針になれればいいなという気持ちで書かれています。


対象者


  • 「なんで書かなきゃいけないの?」と心から不思議に思ってる方

  • 「どう使うのかも、何を書いたらいいのかもわからない……」とお困りの方

  • 「チーム内で書くようにしてるけど、みんな形式がバラバラでどうしようもない……」とお嘆きの方

  • 「書けって言われたけど、イチイチ書くのメンドクセ」な方


目標


  • 「これはIssueもMRも大事だぞ!」と納得できる

  • 「書き方も内容も一通りイメージがついたぞ!」と明るい気持ちになる

  • 「チーム内の書き方がそろったので、効率が上がったぞ!」と定時ダッシュが可能になる

  • 「まあこのくらいならやってもいいかな」と前向きな気持ちになる


IssueとMRはなんで必要なの?

ズバリ、プロジェクトを見返したときに、いろいろなことを思い出しやすくするためです。

ちょっとしたスクリプトであっても、始めてから日が経ったり、割り込み業務を片付けてたりしたら色々忘れてしまっていた!なんてことありますよね。

たいていの人はメモ帳に書いておいたり、メールが残っていたりするから大丈夫!……と思っているかもしれませんが、

「それ、すぐに取り出せますか? 正確にさかのぼれますか?」

こう聞かれると、「ウッ……」となる人も中には多いのではないでしょうか。

大きな利点として、IssueやMRはプロジェクト毎にスレッド形式で残すことができます

「このプロジェクトで見つけたバグ」「当初の予定と変わった出力ファイル」「追加で必要になったモジュールの機能」など、IssueやMRで書いておけば、あとから自分が見返しやすいのはもちろん、途中から手伝ってくれることになった人も追いかけやすくなります。

スレッド形式ってこんな感じです。イイネ!とかもできます。

image.png


どうやってIssueやMRを作成するの?

ここでは一番シンプルだろう作成方法をそれぞれご紹介します。

このほかにももちろんやり方はありますので、慣れた方や好奇心旺盛な方はいろいろ調べて試してみてください。


Issueの場合


  1. プロジェクトのトップページから、左側のツールバーのこのアイコンをクリック。
    スクリーンショット 2018-10-01 時刻 21.13.29.png

  2. 緑の「New Issue」ボタンをクリック
    スクリーンショット 2018-10-01 時刻 21.17.37.png

  3. 書き込みページに映るので、タイトルと内容を書き込んで、緑の「Submit Issue」ボタンをクリック。
    (Assigneeなどはいったん気にしないでOKです)
    スクリーンショット 2018-10-01 時刻 21.21.20.png

  4. これで完成です。
    スクリーンショット 2018-10-01 時刻 21.22.51.png


MRの場合

issueの場合とほとんど同様ですが、途中にブランチの指定が入ります。

1. プロジェクトのトップページから、左側のツールバーのこのアイコンをクリック。

スクリーンショット 2018-10-01 時刻 21.25.30.png

2. 緑の「New merge request」ボタンをクリック。

スクリーンショット 2018-10-01 時刻 21.27.37.png

3. どのブランチをどのブランチにマージするかを指定して緑のボタンをクリック。

スクリーンショット 2018-09-26 時刻 22.24.02.png

4. 書き込みページに映るので、タイトルと内容を書き込んで、緑の「Submit merge request」ボタンをクリック。

(Assigneeなどはいったん気にしないでOKです)

スクリーンショット 2018-09-26 時刻 22.28.20.png

スクリーンショット 2018-09-26 時刻 22.30.35.png

5. これで完成です。


で、何を書けばいいの?(活用方法について)


Issueの場合

Issueには「すぐに手を付けるわけじゃないけど、やらないといけないこと」についてを書きます。

具体的には、要件の整理やto-do、バグについてです。

個人的には「何が課題で」「どうしたくて」「どんな解決方法を自分では思いついているか」を書くと、思考の整理にもなるので良いのではないかと考えています。


記入例

マークダウンで書いていきます。

(改行時は、半角ブランク×2をお忘れなく!)


for_Issue


# 概要
XXX.pyの文字化けについて

## どうしたいか
- エクセルからテキストファイルへの書き出し時に文字化けするのを直したい
- エクセルファイルのほうはいじりたくない(上司の希望)

## どうすればいいか
- [ ] 書き出し時に文字コードのオプションをつける
- [ ] エクセルファイルのほうをどうにかしてくれるように懇願する
- [ ] そもそもエクセルファイルを廃止して最初からテキストファイルにしておく

## 想定される問題点
- [x] 文字コードのオプションが付けられない(→あることは確認できた!)
- [ ] 上司の要望通りにしなければならない(交渉はとん挫する)



実際の見え方

チェックボックスはあとからチェックを入れたり外したりできて、なおかつ履歴にも残ります。

この場合、試した解決方法や解決した問題点にはチェックを入れるというイメージです。

スクリーンショット 2018-10-01 時刻 21.37.06.png


MRの場合

MRには「もうやり始めていること」を書きます。

具体的には、すでに取り掛かり始めているモジュールの開発や修正などです。

モジュールの動作の過程などを具体的に書くことによって、実装漏れをなくしたいという気持ちが強いです。

また、もしも自分がコーディングしたものを誰かにチェック(レビュー)してもらえる環境にいるなら、その人が見やすいようにポイントを書いておくのも親切です。


記入例

マークダウンで書いていきます。

(改行時は、半角ブランク×2をお忘れなく!)


for_MR

## 概要

XXX.pyの開発

### この機能について
- [x] エクセルファイルを読んで
- [x] 読み込んだ数字をちょっと計算して
- [ ] テキストファイルに書き出す

### 特にチェックをお願いしたい箇所
- [ ] 計算部分があっているか
- [ ] 書き出しの際の文字コードの指定があっているか

### その他になるところや、添付画像など
使用するエクセルのシートを、独立してファイルにしておいたほうがいいかも?



実際の見え方

チェックボックスはあとからチェックを入れたり外したりできて、なおかつ履歴にも残ります。

この場合、コーディングが済んだ工程や、レビューが済んだポイントにチェックを入れるというイメージです。

スクリーンショット 2018-10-01 時刻 21.39.40.png


いちいちこの内容をイチから書くの?(テンプレート化について)


テンプレートの作り方

Masterブランチのリポジトリーのトップに

.gitlab/issue_templates/.gitlab/merge_request_templates/

と言うディレクトリーをそれぞれつくります。

リポジトリーのトップとは、「.git」ファイルがあるディレクトリーのことです。

ここではIssueテンプレートをブラウザ上から作ってみることにします。


  1. プロジェクトのトップページから、ブランチ名がでている所の「+」ボタンをクリックし、「New directory」を選択

    スクリーンショット 2018-10-01 時刻 21.49.58.png


  2. .gitlab/issue_templates/と言うディレクトリー名とコミットメッセージを入力して「Create〜」の緑のボタンをクリック。

    スクリーンショット 2018-10-01 時刻 21.52.59.png


  3. 作成したディレクトリーのなかで更に「+」ボタンをクリックし、「New file」を選択。

    スクリーンショット 2018-10-01 時刻 21.55.07.png


  4. 好きなファイル名(拡張子は.mdにする)、テンプレートの内容、コミットメッセージを入力して緑の「commit〜」ボタンをクリック。

    スクリーンショット 2018-10-01 時刻 21.58.57.png


  5. これで完成です。



テンプレートの使い方

さて、ここまでくれば後は簡単。

テンプレートファイルを作成したあとは、Issue、MRそれぞれ内容の入力をする際に、

以下のようなテンプレートを選ぶメニューが現れるので、ここから選択します。

ここから選ぶと、

image.png

こうなります。

image.png

めちゃくちゃ簡単。

これで多少面倒さが緩和されるので、IssueやMRを格ハードルを一段下げることができますし、書く内容も統一させられます。


(おまけ)テンプレート内容の実例

以下二つが私が実際に使っているテンプレートです。

とりあえずこれをコピペして、前述のテンプレート化の方法をなぞれば簡単にテンプレートが作れます!

試しに使ってみてください。


template_for_issue

# 概要

タスクの内容を簡潔に。(タイトルと同じでもOK)

## どうしたいか
- 何故、何を
- どのような状態にしたいのか
- 箇条書きで書く

## どうすればいいか
- [ ] 思いつく解決方法を
- [ ] 箇条書きで
- [ ] 書く

## 想定される問題点
- [ ] 上記の「どうすればいいか?」を実際に行ったとき
- [ ] 躓きそうな部分や不安な部分を
- [ ] 箇条書きで書く

## その他
添付画像など



template_for_MR

## 概要

XXX.pyの開発(タイトルと同じでもOK)

### この機能について
- [ ] 大まか機能を
- [ ] 箇条書きで簡潔に
- [ ] 書く

### 特にチェックをお願いしたい箇所
- [ ] 不安な部分を
- [ ] 箇条書きで簡潔に
- [ ] 書く

### その他になるところや、添付画像など
依頼内容と違うけれど、こうしたほうがいいかも?など気づいたことなどを書く。



おわりに

いろいろ書いてみましたが、これらはあくまで一つの考え方、使い方です。

もっと他にしたことがある、もっとこうしたほうがいいというアイデアがあれば、どんどん実践してください。そして私にご教示ください。

でももし前述したように、GitLabを使っていながらIssueやMRなんて無関係……と考えている方がいたら、ぜひこの記事で書いたことを試してみてほしいです。

IssueやMRを通して、チームメンバーとアイデアを出し合い、レビューをしあう文化を作ることができたら、プログラミング以外の業務もきっと円滑になるはず。

「GitLabを使いこなすために」ではなく、「業務効率化のために」という気持ちで取り組んでみるのはいかがでしょうか。

それでは皆さま、よきGitLabライフをお過ごしください!!


参考URL

Gitlab Issue/MR template