ここでは、GitHub 上で行うことができる開発を進めていく上でとても便利な機能について紹介して行きます。
Issues はプロジェクトやソースコードの課題を管理するための機能で、各リポジトリごとに管理されています。
この様に一覧で何をやる必要があるかを確認することができます。
作り方
まずはリポジトリの Issues タブへ行き、「New Issue」を押すと作成ページが出てきます。
タイトルに課題の内容を簡単に書き、コメントに詳細を書きます。
コメントはマークダウン形式で書くことができます。
また、画像をドラッグ&ドロップすることでアップロードも可能なので、分かりやすくなるように画像を追加するといいでしょう。
④ については、後ほど説明します。
最後に「Submit new Issue」で Issue の登録が完了します。
この Issue に対してコメントをすることもできます。
他の人が作った Issue に対しての質問や詳細について議論することが可能です。
課題が解決したら「Close Issue」を押してクローズします。
クローズした Issue を一覧から確認することができます。
Issue には以下のような便利な機能があります。
- Assignees
- Labels
- Milestone
これはIssue に担当者を定める機能です。Issue のサイドバーの「Assignees」からユーザーを選択することができます。
これを定めることにより誰がどのくらいタスクを抱えているかがわかるので、チーム開発ではとても便利な機能です。
また、これを設定すると担当者が通知を受け取ることができます。
これは増えたIssue にラベル付けをし分類、整理できる機能になります。
これも Issue のサイドバーから選択することができます。 ラベルはデフォルトでいくつか種類があります(bug, puestion, etc...)。
ラベルは複数選択が可能で、一覧からフィルタリングをすることもできます。
ラベルは自分たちが好きなように追加、編集することが可能です。
サイドバーの「Edit lavels」または、Issues 一覧の「Labels」から、一覧を確認することができます。
このページから追加、編集ができ、
- 名前
- 説明(任意)
- 色
を入力して追加、編集を行います。
ラベルがあるのとないのでは、見やすやが全然違いますね。
ラベルなし
ラベルあり
これを使うことによって、機能単位の予定日やリリース日の予定日などのスケジュールを設定することができます。 これは Issue ごとに期限を設けるのではなく、先に Milestone を作成してそこに Issue を紐付けします。
作り方
Issues のページから「Milestones」を選択し、「New milestone」を選択します。
タイトル、期限、詳細を入力し「Create milestone」を押せば作成されます。
その後、各 Issue のサイドバーからそれに対応させたい Milestone を選択することで完了になります。
一覧から何％クローズされたかという進捗を見ることができます。
詳細にいくと、どの Issue が紐づいているかも確認することができます。
基本的な使い方 その 3で、Pull Request の作成の仕方を書いていますが、ここではその時に説明を省いた、
③ 番についての説明をして行きます。
Issues と同じように Pull Request にもさまざまなものを設定することができます。
Issues と違うものは、「Assignees」が「Reviewers」に変わっただけです。
Reviewer は Pull Request をレビューして欲しい人を選択します。
選択された人のもとには通知が飛びます。
Fork とは、自分以外のユーザが管理するリポジトリのコピーを自分のリポジトリに作成することです。
Fork を使用すると、他の人が公開しているリポジトリに対して、自分が変更を加え、その Pull Request を出すことができます。
OSS の開発などでよく、Fork して Pull Request が出されているのを見かけます。
Fork はリポジトリの右上の「Fork」から行えます。
すると、以下のように、自身のアカウントの中にリポジトリが複製されます。
仮に、修正して Pull Request を出してみます。
すると、以下のように自分のフォークしたリポジトリから、元のリポジトリへ Pull Request を出すようになっています。
これで作成を完了することによって、個人のリポジトリからハックツのリポジトリへ Pull Request を出すことができました。
もちろんこれは、勝手にマージすることはできないので、Fork 元のオーナーが認めた時のみマージされます。
この資料でもし間違っているところを見つけた場合などには是非 Fork して Pull Request を出してみてください。
Projects を使用するとタスク管理機能が簡単にできるようになります。 これによって「今どんなタスクが進行しているか」「どのタスクが終わっているか」など、進捗具合やタスクの状態を確認することができます。
Projects はユーザー毎に作成されます。
しかし、基本的にはリポジトリ毎で Project を扱うことが多いと思いますので、一つの Project での扱い方を解説します。
Project はテーブル形式または、かんばん形式で作成することができます。
まずはかんばん形式での使い方を説明して行きます。
かんばん形式は columns と cards から構成されていて、columns の中に cards が存在しています。
また、それぞれ複数作成することが可能です。
では、実際に作成して行きます。
はじめに、Projects のタブから「New project」を選択するとモーダルが表示されるので、
「Board」を選択して「Create」を押します。
これで以下のような画面が出てきたら OK です。
この画面からカードを追加して行きます。画面下部の「Add item」を選択します。
すると以下の様にフォームが出てくるので、ここにカードのタイトルを入力していきます。
Enter を押すとカードが追加されます。
この様にこの「Test」というタスクは現在は「Todo」の状態である、というふうにこれを見ることができます。
また、このカードには作成した「Issue」や「Pull Request」を追加することができます。
試しに下のフォームに "#" と入力します。
すると以下の様にリポジトリが出てくるので、現在触っているリポジトリを選択します。
すると以下の様に、作成した「Issue」や「Pull Request」が表示されます。
これを選択することによって「Issue」や「Pull Request」をカードとして追加することができます。
基本的には、カードには「Issue」と「Pull Request」しかないように作るとタスク管理がやりやすくなります。
また、先ほど追加したカードを「Issue」へ変化させることができます。
カードのメニューを選択し、「Convert to issue」を押します。
そして、リポジトリの選択することによって、「Issue」へと変化します。
Project への反映は、Issue や Pull Request を作成するタイミングで生成することもできます。
これらのカードはドラッグ&ドロップで移動させることができます。
作業中なら「In Progress」へ、終了したら「Done」へと移動させることによって、
タスクの進捗具合を確認することができます。
また、Project から Issue や Pull Request を選択することによって同じページのまま、中身を確認することができます。
基本的にはもうこの Project のページのみを見ながら開発を進めていくという感じです。
さらに、Project にカラムを追加することができます。
これを追加することによって、タスクの状態をより詳細にすることができます。
追加の方法は、「+」ボタンからカラムの名前を入力することによって新しく追加することができます。
カラムもドラッグ&ドロップで順番を変えることが可能です。
表示順番をタスクの進行と同じようにすることによって、分かりやすくなります。
また、テーブル形式へレイアウトを変更することもできます。
View の詳細から「Table」を選択することによって以下の様に表示が切り替わります。
View の追加で、かんばんもテーブルもタブで切り替えることができるようにすることが可能なので、
その設定を入れるのもありかもしれません。
また Table 形式では、Project の fields を自分の好きなようにカスタマイズすることもできます。
カラムの「+」ボタンから一覧表示する fields を選ぶことができ、さらに追加することも可能です。
これらの編集を行なった際には、「Ctrl + s」または「Cmd + s」で変更を保存してください、
試しに「Tag」というものを追加してみました。
この機能と、フィルターの機能を上手く使うことによって、
バックエンドとフロントエンドを別々の View で管理することが可能になります。
しかし、これを作業中いちいち動かして状態を更新するのは、面倒ですし人に依存してしまいます。
そんな時に、Workflowsという機能を使うことで、Issue や Pull Request が作られた時や閉じられた時などに自動でカードを移動してくれます。
設定は、Project の右上のメニューから Workflows から行います。
すると、以下の様な画面が表示されます。
簡単に説明を行うと、
- ここで、どの条件の時に何が行われるかということがわかります。
画像の例では、「Issue, Pull request が閉じられた際に、そのカードが Done に移動する」ということが示されています。 - ここで、この Workflow が実際に適応されているかどうかを設定することができます。
- ここは、Issue や Pull request が作成された時や閉じた時レビューされた時などのトリガーを選択することができます。
デフォルトで用意されているのはここに書いてある分のみです。それ以外にカスタマイズしたい場合には Actions を使用します。
では、実際に少し編集してみます。
「Item addded to project」を選択してみます。
ここでは、Issue と Pull request が追加された際に、Todo のカラムにカードを追加することを示しています。
現状では、これが適応されていないため、「On」を選択してこの Workflow を有効にします。
また、どのカラムにセットするのかをカスタマイズすることができます。
Set 以降の Status を選択し、自分のやりたいカラムを選択することによって編集することができます。
さらに、それぞれのトリガーで、Issue なのか Pull request なのか両方なのかを選ぶこともできます。
これらを使って、自分の好きなトリガーで Project を操作することが可能です。
先ほど、より細かいカスタマイズは Actions を使うと言いましたが、Actions については次のセクションを参考にしてください。
Actions は開発でのワークフローをリポジトリの中で自動化することができます。
例えば、mainブランチにマージした時にデプロイを行なったり、Pull Request を作成した時にテストを走らせたり、Project でのフローをより複雑にカスタマイズしたりなど、様々なことすることができます。
GitHub の Actions は .github/workflows/ 以下に yaml 形式のファイルで書かれます。
では、実際に作ってみます。
まずは、Actions のページへ行きます。
今回は例として、「Automation」の「Manual worlflow」を選択してみます。
すると以下の様な画面になると思います。
今回はこのコードをそのまま使っていこうと思うので、そのままコミットします。
簡単にこのコードの説明を行うと、
まず、nameはこの Actions の名前を指定します。
何を行うものかを指定するといいです。
次に on ですが、ここでは Actions を走らせるトリガーについて記述します。
ここでは、workflow_dispatch が設定してあります。
workflow_dispatch イベントはワークフローを手動で実行できるイベントです。
この他にも、 Pull Request を作成した時に実行できるpull_requestや定期実行を行うscheduleなど様々なものがあります。
また、workflow_dispatchの下に書いてあるinputを記述することで実行の際に入力項目を追加することができます。
これで任意の変数などを追加することができます。
最後のにjobsは実際に行う操作を記述して行きます。
greet は job の名前を示しています。
runs-on には実行環境を記述します。
steps 以下に実行するものを順番に書いて行きます。
name に実行するステップの名前、runに実際に実行するコマンドを記述します。
また、ここでは書いてありませんが、envというものを指定できます。
ここには、環境変数などの GitHub 上にあげたくない値を変数として、記述します。
envの値は「settings」のサイドメニューの「Secrets」の「Actoins」から追加することができます。
これで、TEST_KEYという環境変数を使うことが可能になります。
${{ secrets.TEST_KEY }}では、実際に作成した Actions を実行させてみようと思います。
Actions のタブから作成した「Manual workflow」を選択します。
「Run workflow」を選択して、設定した input に任意の文字列を入力します。
すると、Actions が実行されます。
では、実行された Manual workflow の詳細を見て行きます。
選択すると、「jobs」で設定したものが出てくるので、さらに選択します。
すると、以下の様にコンソールのような画像が表示され、setp ごとに詳細を見ることができます。
実際に中身を見てみると、run で指定したように Hello take_cantik と出力されています。
このように様々なことを実行することができます。
この機能をうまく使うことで、CI/CD を組むなどの自動化を行うことができます。
詳しいことは、たくさん調べてみましょう！
これはその名の通りリポジトリ内の wiki 機能です。
GitHub 公式ではプロジェクトの利用方法、設計方法、中核的な原理などプロジェクトに関する長いコンテンツを共有するために利用すると説明されています。
README では手短にプロジェクト内容を述べていますが、これを使えば追加のドキュメンテーションを提供できます。
リポジトリの Wiki ページへ行き「Create the first page」すでにある場合は「New Page」から作成することができます。
記述形式を 9 種類(Markdown, Mediawiki, etc...)から選択できます。
その他ページの追加や、特殊ページを追加することができます。
「Save page」を押すことで、追加することができます。
- Home : wiki を開いた時の Top ページ。(タイトルを変更すると通常のページになるので注意)
- _Sidebar : 常に wiki の横に表示されるページ。目次などで便利。
- _Footer : 常に下に表示されるページ。
実際に、それぞれのページを書いてみると以下のようになります。
(内容が少ないので、見にくいかもしれませんが)
これらの機能を使えば開発をスムーズに行うことができます。