社内文書管理はGitHubで！非エンジニアのためのGitHub講座

社内文書を GitHub で Git 管理すると、版管理がしやすかったり、レビューによって変更点を関係者が見られたりといろいろ便利なので、最近社内の一部文書を GitHub に移行しています。

また、先日 Cookpad 開発者ブログで Markdown と GitHub で社内規程を便利に管理 という記事が公開されました。
https://techlife.cookpad.com/entry/2019/06/26/182322

きっとうちに限らずいろんなところでエンジニアが非エンジニアに GitHub をポチポチする方法を教えたりしているかもしれないと思ったのでまとめます。

エディタを使わずコマンドも打たない、github.com 上でファイルの編集から Pull Request を作るまでを完結させる方法です。なるべく非エンジニアもわかるように書いたつもりですが、なにかあれば編集リクエストをください。

*ここでは markdown の説明はしません。

超簡単に Git / GitHub の用語説明

GitHub の UI 上で完結させることの利点の 1 つは、 Git の知識をほぼほぼ必要としないことです。
なので必要最低限の説明にとどめます。Web UI だとできることが限られているのでちゃんと理解する必要はなく、使っているうちにわかってくると思います。

• Pull Request
  • 文書やソースコードの変更を提示して「こういう変更しようと思うんですが、どうでしょう？」という提案をするもの
• Reviewer
  • 「この変更どうでしょう？」と聞く相手
• commit
  • 変更(差分)のまとまり
• branch
  • 他人と作業がかぶっても大丈夫なように自分用の作業場所として作るのが　branch です。ここにコミットをまとめて Pull Request にします。

詳しく書いている記事は世の中にめちゃめちゃあるのでもっと知りたい方はそちらを参考にしてください
おすすめは↓です
https://qiita.com/yunico-jp/items/87bdd13971e82833f6bb

Pull Request を作ってレビューを依頼する

ファイルの作成・編集

ファイルを新規作成するとき:	既存のファイルの編集をするとき:

編集画面はこんなかんじです

ちなみに、ファイル名に / 区切りで入力することで新たにフォルダを作ることもできます。

Pull Request を作る

編集できたらを Pull Request を作成します。
テキストフィールドの下にある Commit Changes のフォームから作成します

• Commit Message を入力
  • 入力しないと Update <変更したファイル名> になる
  • どんな変更をしたのか書く e.g.) Add FAQ part
• Create a new branch for this commit and start a pull request を選択
  • 合わせて branch 名を設定する
  • このままでも良いけど、チームによって規則があることが多い。 <username>/<変更内容> とか

Propose file change をクリックするとこんなビューになります。

説明には、

• Why: なぜこの変更がしたいのか
• What: 具体的にどんな変更をしたのか

を書きましょう。 これがあると、「なんでこここうしたんだっけ」といったコミュニケーションが省けるだけでなく、 Reviewer が Review しやすくなり、早く Review してもらえる確率があがります。
効果的なプルリクの書き方は以下にまとまっているのでぜひ見てほしいです。
https://qiita.com/umanoda/items/93aec41213f8e3ce14c8

タイトルと説明をかいたら Create pull request をクリック。

1つの branch (Pull Request) に複数のコミットを含める

作成した Pull Request に、他の変更も合わせたいときの方法です。
まず Pull Request のビューで今作った Branchのリンクをクリックします。

リポジトリのトップに飛びますが、ブランチがさっき作った branch になっています。この状態で、ファイルの作成・編集をします。

Commit Changes のフォームで、今度は Commit directly to the takose-patch-1 branch. のままでコミットメッセージを入力して Commit changes をクリックします。

さっき master となっていた箇所が takose-patch-1 になっています。これは「さっき作った takose-patch-1 という branch に commit を追加する」という意味です。

これでさっき作った Pull Request を確認します。 Pull Request を探すには、上部の Pull Request タブをクリックすると一覧が見られます。

さっき作った Pull Request を確認すると、コミットが追加されています。

Reviewer を指定する

サイドバーで Reviewer を指定したら　Reviewer からの反応を待ち、必要に応じて修正などをします。

変更を反映 (merge) する

Reviewer から Approve がもらえて変更を反映するときは、 Merge pull request → Confirm merge とクリックしていくと、変更が反映されます。

レビューのしかた

変更を確認する

レビューを依頼されたら、まず変更を確認します。
変更を確認するには、Files changed タブをクリックします

こんな感じで差分が表示されます。

コメントをする

Conversation タブで普通にコメントする他に、特定の行にコメントをすることができます。コメントしたい行の左端あたりをホバーすると + アイコンが出るので、クリックすると、コメントのフォームがでます。

詳細は省きますが、Add single comment をするとこのままコメントが 1 つポストされ、 Start a review をすると、複数のコメントまとめて 1 度にポストできます。基本的には Add single comment を使うのでいいと思います。

レビューをつける

全部見終わったら、画面右上の Review changes で review の結果を選びます。
どれを選ぶか、厳密にルールが決まっているわけではないですが、大まかには以下のとおりです。

• このまま変更を反映してよければ Approve
• 修正した方がいいところがあれば Request changes
• 判断がつかず、聞きたいことがあるときなどは Comment

Approve 以外のときは、相手の反応や修正を待ち、再び Review して Approve がでるまで繰り返します。

Tips

差分表示のレイアウト

差分表示のレイアウトは、デフォルトだと差分が1行ずつ表示されていますが、変更の前後を左右で割って表示させる方が個人的には見やすくておすすめです。歯車マークをクリックして、 Split を選択して Apply and reload すると変えられます。

1行の変更だと大して変わらないですが、このようになります。

suggestion

Pull Request のコメントには、 suggestion の機能があります。
テキストフィールドの上にあるファイルアイコンをクリックすると、以下のように指定した行の内容が自動で記入されます。これを編集すると、

こんな感じで、修正を提案できます。

レビューされた人は、Commit suggestion から簡単にこれを取り込むことができます。

最後に

社内文書を GitHub で Git 管理して幸せになろう 😜