GitHubをチームで利用する場合のプラクティス
Masayoshi Tohna@おれさまラボMotivation
複数人で設計書を書く機会があり、GitHubを活用している。すでにやっていることは以下の通り。
| No | タイトル | 詳細 | ステータス |
|---|---|---|---|
| 1 | markdownで下書きする | 各章をメンバーで分担して執筆 | 運用中 |
| 2 | pandocでdocxへ変換 | GitHub Actionsを使って特定のタグをつけたコミットについては変換処理を実行 | 運用中 |
| 3 | 第n版として体裁を整えて納品 | pandocだけだと体裁表現に限界があるので微修正 | 運用中 |
これをやってみてわかったのは、STEP1である「markdownで下書き」の部分でGitHubを活用しきれていない。
- メンバーが分担して執筆
- プルリクエストされたものをリーダーがレビュー
- プルリクエストをリーダーが承認してmainブランチにマージ
上記の流れでやりたいのがだ、どうやってブランチを切るべきかが悩ましい。どういったベストプラクティスがあるのかググって方針を決めたい。
Masayoshi Tohna@おれさまラボトピックブランチ
トピックブランチという考え方があるらしい。ブランチって各々が作っていくものなのね。Git初心者すぎて知らなかった
GitHub上でもブランチにOpen/Closedというステータスがある。なるほどね。
Masayoshi Tohna@おれさまラボということは、章（はデカイから節くらい？）単位とかでトピックブランチ切ってもらって、それぞれ書いてもらって、コミット単位は人それぞれおまかせ、書き終えたらプルリクエストを送ってもらってリーダーがmainブランチへマージ、マージ後にトピックブランチをCloseする運用かな。
Masayoshi Tohna@おれさまラボGitHubには draft pull request というステータスもあるらしい。へぇー。
Masayoshi Tohna@おれさまラボプルリクエストの単位
レビューしながら思ったのは誤字脱字系を１つ１つプルリクエストされても面倒だなと思った。指摘事項としてはIssueやExcel票などで１つ１つ管理すべきだが、修正のプルリクエストは１つにまとめる運用としたい。
Masayoshi Tohna@おれさまラボOSSのコントリビューション・ルールから学ぶ（#1：rubygems）
Masayoshi Tohna@おれさまラボラベルの色
全部の色を変えるんじゃなくて、カテゴリで同じ色にする使い方はわかりやすそう。なるほど。
Issues might have a light green type: * label, which describes the type of the issue.
Masayoshi Tohna@おれさまラボIssueのカテゴライズ
Issueには薄い緑色のラベルをつける。
- bug report：バグに関わるIssue
- feature request：新しい機能や機能強化の要求に関わるIssue
- question：質問を扱うIssue
- cleanup：処理は変えずにコードをキレイに書き直す場合のIssue
- major bump：メジャーバージョンアップが必要なIssue
- administrative：管理者向けのIssue
- documentation：ドキュメントの更新に関わるIssue
Masayoshi Tohna@おれさまラボプルリクエストのカテゴライズ
プルリクエストには、薄いオレンジのラベルをつける。
- security fix：セキュリティの問題を修正するプルリクエスト。
- breaking change：メジャーバージョンアップを必要とする変更を含むプルリクエスト。
- major enhancement：下位互換性のある変更を含むプルリクエストで、変更ログで特別に言及する価値のあるもの。
- deprecation：非推奨事項を導入するプルリクエスト。
- feature：feature リクエストを実装したプルリクエスト。
- deprecation：パフォーマンスの改善を実装するプルリクエスト。
- documentation：エンドユーザに言及する価値のあるドキュメントの改善を紹介するプルリクエストです。
- minor enhancements：ユーザーが目にするような小さな変更を紹介するプルリクエスト。
- bug fix - バグレポートを修正するプルリクエスト。
Masayoshi Tohna@おれさまラボステータスを表すラベル
- triage：メンテナが適切にラベルを貼る必要がある課題やプルリクエスト。
- confirmed：作業できる状態ではない課題やプルリクエスト。
- ready：共同作業が可能な課題。
- 作業中：特定の担当者が割り当てられ、その作業を計画している課題。
- user feedback required - エンドユーザーからのフィードバックが必要な課題やプルリクエスト。
- blocked / backlog：一般的に、これは RubyGems の外にある理由であったり、特定の個人やグループからのフィードバックを必要とする理由であり、それが解決されるまでにはしばらく時間がかかるかもしれません。
Masayoshi Tohna@おれさまラボOSSのコントリビューション・ルールから学ぶ（#2：googletest）
Masayoshi Tohna@おれさまラボコントリビューションの手順
- 提案された変更点を記載した課題を課題トラッカーに提出してください。
- 履歴を追うのが困難になるので、1回の提出につき複数の論理的な変更を混ぜないようにしてください。issue trackerに対応するissueがない変更を行いたい場合は、issueを作成してください。
- また、問題の課題にリストアップされているチームメンバーと調整してください。そうすることで作業が重複しないようにし、早めに計画を伝えることで、一般的にはより良いパッチを作成することができます。
- 提案された変更が受け入れられ、まだ変更を行っていない場合は、コントリビューターライセンス契約書に署名してください (上記の詳細を参照してください)。
- 希望するレポをフォークし、変更したコードを開発してテストします。
- あなたのコードが、投稿先のサンプルの既存のスタイルに準拠していることを確認してください。
- あなたのコードが適切なユニットテストのセットを持っていることを確認してください。
- プルリクエストを送信します。
Masayoshi Tohna@おれさまラボOSSのコントリビューション・ルールから学ぶ（#3：azure-docs）
参考：azure-docs/CONTRIBUTING.md at master · MicrosoftDocs/azure-docs
やりたいことはドキュメント管理だから、ドキュメントのリポジトリを読んだほうが幸せになれるのではと思った。
Masayoshi Tohna@おれさまラボこっちに詳細が書いてあるみたい。
参考：Microsoft Docs 共同作成者ガイド概要 - Contributor Guide | Microsoft Docs
Masayoshi Tohna@おれさまラボマイクロソフトの場合は、ドキュメントページからやる感じだからちょっと参考にならないみたい。
Masayoshi Tohna@おれさまラボOSSのコントリビューション・ルールから学ぶ（#4：aws-cli）
Masayoshi Tohna@おれさまラボ注意点
- PR は develop ブランチをターゲットにすること。
- PR ブランチは develop ブランチの最近のコミットをベースにすること。
- PR のベースとなるコミットは、PR が作成された時点での develop の最新のコミットを使用するのが望ましい。
- PR が develop ブランチにマージされたときにマージの競合やテストの失敗がないことを確認するのに役立つ。
- 論理的に別々の変更に対しては、別々のコミットを行うこと。
- update"、"faix typo again"、"more updates" などのコミットは避ける。
- コミットが論理的な変更であることを確認するために、PR を提出する前にコミットをリベースすること。
- PR でのマージコミットは避ける。
- develop ブランチから最新の変更を取り込みたい場合は、develop ブランチを feature ブランチにマージするのではなく、develop ブランチの上にリベースする。
- コミットメッセージのフォーマットに準拠すること。
Masayoshi Tohna@おれさまラボコミットメッセージに関する注意点
短く（50文字以内）まとめ
50文字の要約と空行の後に、必要に応じて本文を入れます。50文字の要約は句読点で終わらないことに注意してください。変更点を命令的な気分で記述してください。例えば、"Add foo to bar", "Update foo component for bar", "Fix race condition for foo".
コミットメッセージの本文には、以下の内容を含めることができます。
問題の説明と、この変更が何を解決しようとしているのか。
特定の実装の背景にある根拠。
考慮された代替案と、それが破棄された理由（適切であれば）を説明してください。
コミットメッセージの本文の行数は80文字以内にしてください。
Masayoshi Tohna@おれさまラボ自分の中での考え方はまとまったので一旦クローズ。やってみて改良できたら、再オープンするかも。
Masayoshi Tohna@おれさまラボ参考になりそうな記事が出てきたのであとで読む。
参考：GitHub Issueを用いた開発手法