******************************* セミナーノート作成の手引き ******************************* :Author: Kenji Sato .. toctree:: :maxdepth: 3 はじめに ======== この資料は, 神戸大学経済学研究科小林ゼミ・Python勉強会参加者がセミナーノートを作成 するワークフローを統一するために作成しています. 特に Git の学習曲線は急勾配なので, 最初はとまどうことも多いかもしれませんが, 間違いを恐れずに手を動かしましょう. 破壊的な間違いは回避されるよう設計されています. 使用ツール =========== このセミナーでは, セミナーノートを Sphinx で作成し, ソースコードを Github で管理・ 公開しています. セミナーノートのレポジトリは https://github.com/rokkopy/qe-seminar にあります. ソースコードは自動的にHTMLに変換され, 結果が次のURLでホストされています http://rokkopy.github.io/qe-seminar/ Git のワークフロー & 用語集 ============================ このセミナーノートは, フォーク型ワークフローを使って管理していきます. Atlassian によるGit チュートリアルの該当部分に目を通しておいてください. https://www.atlassian.com/ja/git/workflows#!workflow-forking 以下, ワークフローについて概略を説明する中で, 用語の解説をしていきます. 実際に作業をしながら理解してください. **手を動かさないかぎり決して身につきません!** レポジトリ ----------- Git でファイル更新履歴を管理しているディレクトリ (フォルダ) を Git レポジトリといいます. 自分のPC内のディレクトリがGitで管理されている場合, それを **ローカルレポジトリ** と いいます. それ以外のレポジトリは **リモートレポジトリ** です. 以下では便宜上 GitHub に保存されているレポジトリをリモートレポジトリと呼びます. フォーク -------- あるプロジェクトのファイルと更新履歴は (普通は) 1つのリモートレポジトリが中央管理し ています. この中央管理レポジトリを便宜的に **upstream** レポジトリと呼びましょう. upstream レポジトリの管理者をメンテナ (maitainer) と呼びます. プロジェクトの開発に貢献しようとする人 (貢献者, contributor) はまず upstream を **フォーク** します. フォークとは, 他の人のアカウントで管理されているリモートレポジトリ をコピーし, 自分の管理下にあるリモートレポジトリを作る作業です. 次に説明する **クローン** をサーバー上で行うということでもあります. GitHub ではウェブのインターフェースでフォークを行います. セミナーのレポジトリ https://github.com/rokkopy/qe-seminar にアクセスし, Fork ボタンを押してみましょう. (下図参照) .. image:: /_static/img/notetaking/fork.png :scale: 30% :alt: Fork Button クローン -------- フォークを行なった結果, 自分が管理しているリモートレポジトリとして **upstream** の コピーが作成されました. .. image:: /_static/img/notetaking/origin.png :scale: 30% :alt: origin このリモートレポジトリを便宜的に **origin** レポジトリと呼びましょう. 今後の作業は, - origin を更新する (プッシュ) - origin -> upstream に更新を反映するよう申請する (プルリクエスト) という2段階の作業によって行います. 作業の第一段階を進めるために, origin レポジトリを手元のPCにコピーしましょう. Git ではレポジトリのダウンロード (コピー) をクローンといいます. 現在公開されている最新版のファイルだけでなく, 過去の履歴も含めてまるごとコピーされます. 適当なディレクトリで次のコマンド (git@ ... 以下は上図の赤枠内を参照):: $ git clone git@github.com:[YOUR USERNAME]/qe-seminar.git を実行すると, カレントディレクトリに qe-seminar というディレクトリ (ローカルレポジ トリ) が作成されます. このディレクトリの名前は変更しても問題ありません. add & commit -------------- これで, プロジェクトに手を加える準備が整いました. Git レポジトリ内では, - ファイルの追加・編集 - $ git add コマンドの実行 (変更したファイルを git に記録するように指示) - $ git commit コマンドの実行 (変更を履歴として残す) を繰り返します. 作業中のファイルが保存されるローカルレポジトリでは, 変更履歴は細かく残しておくほうがよいでしょう. リモートに反映させるときには あまり細かい履歴が残ると困るケースもあるので (逡巡が見えてしまう ... ), ローカルの履歴を書き換える操作が可能です. 当面そのような履歴の美しさにこだわる必要はないでしょう. ``git add`` はコミットに含める (インデックス) するファイルとして登録する操作です. ``git commit`` はインデックスされたファイルについて変更を履歴として保存する操作です. ``add`` されていないファイル (例えば自分のためのメモみたいなファイルとか) は無視して, 本当に必要な変更だけを記録することができます. コミットには必ずメッセージが要求されます. メッセージを入力する簡単な方法は, :: $ git commit -m "Message Here" とやることです. どんな変更を記録したいかが分かる簡潔なコメントを書きましょう. Git のコマンドをまったく触ったことがないという方は, まず手始めに tryGit の15分コースを実践してみてください. https://try.github.io/levels/1/challenges/1 また, `Atlassian Git チュートリアル 「Gitの基本」 `_ に目を通しておいてください. プル ----------- もしかすると, 自分が作業をしている間にも他の人が作業して upstream (プロジェクトの中心となるリモートレポジトリ) が更新されているかもしれません. upstream の更新をこまめにチェックするというのは大切なことです. クローンしただけでは, upstream からフォークしたものだという情報が記録されていませんので, シェルコマンド:: $ git remote add upstream https://github.com/rokkopy/qe-seminar.git を実行して, upstream の情報をローカルレポジトリに追加しましょう. このようにしてから, 作業中の変更をコミットし, :: $ git pull upstream を実行してください. upstream の更新をローカルレポジトリに反映することができます. 注意. プルというのはリモートのダウンロード (fetch) + マージ (merge) を同時に やるコマンドです. 他の人が更新したファイルと同じファイルを自分も更新していた場合には, **コンフリクト** が発生し, マージが失敗します. 失敗の状況を確認するために:: $ git status コマンドを実行し (このコマンドはレポジトリの状態を確認するために頻繁に使います), コンフリクトが発生しているファイルを認識しましょう. 次のような部分があるはずです.:: <<<<<<< HEAD ======= >>>>>>> upstream/master ======= の上部が手元にあったコードで, 下部が upstream にあったコードです. どちらのコードを残すべきかを検討し, コンフリクトを解消してください. コンフリクト 解消のために使えるツールの解説を含め, 詳細は `Pro Git 「ブランチとマージの基本」 `_ を参照してください. コンフリクトが解消されたら, それを Git に伝えるために, git add と git commit を 行います. プッシュ -------- たくさんの試行錯誤と推敲, たくさんの ``git add`` と ``git commit`` を 繰り返した結果, ローカルの内容をインターネットに公開してよいレベルに達しました. このとき, いきなり upstream に公開するのではなく, 一度 origin レポジトリ (自分が 管理しているリモートレポジトリ) に公開するという手順を取ります. (フォーク型のワークフロー を採用していることを思い出してください). この段階で使うコマンドが ``git push`` です. ``git pull`` を実行して, あなたの 作業が upstream の最新版の成果に基づくものであることをもう一度確認してください. その後, :: $ git push origin master を実行します. これで, origin = upstream + あなたによる更新 という状態になりました. 要するに, **プッシュ** というのは, 手元の更新をリモートレポジトリに反映させる作業です. 補足. upstream は ``git remote add upstream ADDRESS`` とやりましたが, origin についてはクローンした時点で自動的に追加されていますので, このような操作は不要です. どのようなリモートレポジトリが登録されているか心配な人は, 次のコマンドの結果を確認してください (``$`` に続く行が入力してほしい行, それ以外はコマンドの出力):: $ git remote show origin upstream $ git remote show upstream * remote upstream Fetch URL: https://github.com/rokkopy/qe-seminar.git Push URL: https://github.com/rokkopy/qe-seminar.git HEAD branch: master Remote branches: gh-pages tracked master tracked Local ref configured for 'git push': master pushes to master (up to date) 最後の部分は異なるかもしれませんが, だいたい上のような出力になるはずです. プルリクエスト -------------- 今, origin は upstream よりも一歩先に進んだ状態になっています. このとき, メンテナに 対して origin の情報を upstream に反映させるように促す行為が **プルリクエスト** と呼ばれるものです. これは, GitHub の origin のサイトにレポジトリページか upstream のレポジトリページ に行けばこれまでなかったボタンが現れているはずです. .. image:: /_static/img/notetaking/pr.png :scale: 30% :alt: PR Button ボタンを押し, 修正に関するコメントを書いた上でプルリクエストを発行してください. メンテナーに通知され, コードレビューの後に問題がなければ upstream が更新 (マージ) されるでしょう. 問題があれば, GitHub 上でディスカッションを行い, マージ可能なレベルに達するまで必要な修正を施します. おまけ: ビルド ----------------- このセミナーのビルド済みのノートは Github Pages で公開されています. これには Travis CI というサービスを利用しており, qe-smemina/master に対するプルリクエストがマージされた時点で, 自動的にビルド・公開されます. したがって, ノート作成者はプルリクエストを送って,コードレビュー後にマージをすればよく, サイトの公開に関する作業を気にする必要はありません. まだ書いていないこと ------------------------ - ブランチについて - ``git rebase`` による履歴の修正 - マージコンフリクトの解消 - ``github pages`` に origin の内容をホストする方法 リンク集 ------------ 必ず読むべきサイト ^^^^^^^^^^^^^^^^^^^^^^ - `Git チュートリアルとトレーニング (Atlassian) `_ 参考 ^^^^^^^^^^^^^^^^^^^ - `ProGit `_ - `サルでも分かるGit入門 `_ Sphinx ========= Sphinx での記法 (ReST) は簡単に学ぶことができます. 例えば, Python の公式ドキュメント も Sphinx で書かれているので, そのソースコードを参考にすればよいでしょう. https://docs.python.org/3/_sources/tutorial/introduction.txt リンク -------- - http://sphinx-doc.org/rest.html