GitとGitHubの操作—Djangoドキュメント
GitとGitHubの操作
このセクションでは、コミュニティがプルリクエストを介してDjangoにコードを提供する方法について説明します。 コミッターがそれらをどのように処理するかに興味がある場合は、コミットコードを参照してください。
以下に、Tracチケット#xxxxxの変更を含むGitHubプルリクエストを作成する方法を示します。 完全に準備ができたプルリクエストを作成することで、レビュー担当者の仕事が簡単になります。つまり、あなたの仕事がDjangoにマージされる可能性が高くなります。
従来のパッチをTracにアップロードすることもできますが、レビューにはあまり実用的ではありません。
Gitのインストール
Djangoは、ソース管理に Git を使用します。 ダウンロード Gitは可能ですが、多くの場合、オペレーティングシステムのパッケージマネージャーを使用してインストールする方が簡単です。
Djangoの Gitリポジトリは GitHub でホストされているため、GitHubも使用することをお勧めします。
Gitをインストールした後、最初にすべきことは、名前とメールアドレスを設定することです。
$ git config --global user.name "Your Real Name"
$ git config --global user.email "[email protected]"
user.name
は、GitHubのニックネームではなく、本名である必要があることに注意してください。 GitHubは、user.email
フィールドで使用するメールを認識している必要があります。これは、コミットをGitHubアカウントに関連付けるために使用されるためです。
ローカルリポジトリの設定
ニックネーム「GitHub_nick」を使用してGitHubアカウントを作成し、フォークされたDjangoのリポジトリを作成したら、フォークのローカルコピーを作成します。
git clone https://github.com/GitHub_nick/django.git
これにより、GitHubリポジトリのクローンを含む新しいディレクトリ「django」が作成されます。 このページの残りのgitコマンドは、複製されたディレクトリ内で実行する必要があるため、今すぐ切り替えてください。
cd django
GitHubリポジトリは、Gitでは「origin」と呼ばれます。
また、django/django
を「アップストリーム」リモートとして設定する必要があります(つまり、参照Djangoリポジトリがフォークのソースであったことをgitに伝えます)。
git remote add upstream [email protected]:django/django.git
git fetch upstream
同様に、他のリモートを追加できます。次に例を示します。
git remote add akaariai [email protected]:akaariai/django.git
チケットの作成
チケットで作業するときは、作業用の新しいブランチを作成し、アップストリーム/マスターで作業するベースを作成します。
git checkout -b ticket_xxxxx upstream/master
-bフラグは、ローカルに新しいブランチを作成します。 どんなに小さなことでも、新しいブランチを作成することを躊躇しないでください-それが彼らの目的です。
代わりに、1.4ブランチの修正に取り組んでいる場合は、次のようにします。
git checkout -b ticket_xxxxx_1_4 upstream/stable/1.4.x
作業がticket_xxxxxブランチで実行されると想定します。 いくつかの変更を加えてコミットします。
git commit
コミットメッセージを書くときは、コミットメッセージガイドラインに従って、コミッターの作業を楽にしてください。 英語が苦手な場合は、少なくともコミットの内容を正確に説明するようにしてください。
ブランチで追加の作業を行う必要がある場合は、必要に応じて何度でもコミットしてください。
git commit -m 'Added two more tests for edge cases'
出版作品
次のコマンドを実行して、GitHubで作業を公開できます。
git push origin ticket_xxxxx
GitHubページに移動すると、新しいブランチが作成されていることがわかります。
Tracチケットで作業している場合は、GitHubリポジトリのブランチticket_xxxxxから作業を利用できることをチケットに記載する必要があります。 ブランチへのリンクを含めます。
上記のブランチは、Gitの用語では「トピックブランチ」と呼ばれていることに注意してください。 たとえば、git rebase
を使用して、このブランチの履歴を自由に書き換えることができます。 他の人は、コミットを編集するとクローンが破損するため、そのようなブランチに基づいて作業するべきではありません。
「公的支部」もあります。 これらは他の人が分岐することになっているブランチなので、これらのブランチの歴史は決して変わらないはずです。 パブリックブランチの良い例は、django/django
リポジトリのmaster
およびstable/A.B.x
ブランチです。
作業をDjangoにプルする準備ができたら、GitHubでプルリクエストを作成する必要があります。 適切なプルリクエストとは、次のことを意味します。
- コーディングスタイルに従って、それぞれに1つの論理変更を加えてコミットします。
- コミットごとの整形式メッセージ:要約行とその後72文字で折り返されている段落–詳細については、コミットガイドラインを参照してください。
- 必要に応じて、ドキュメントとテスト–ドキュメントの変更を除いて、実際には常にテストが必要です。
テストスイートに合格し、ドキュメントを警告なしで作成する必要があります。
プルリクエストを作成したら、関連するTracチケットにコメントを追加して何をしたかを説明する必要があります。 特に、テストを実行した環境に注意する必要があります。たとえば、「すべてのテストはSQLiteとMySQLで合格します」。
GitHubでのプルリクエストには、オープンとクローズの2つの状態しかありません。 プルリクエストを処理するコミッターには、マージするか閉じるかの2つのオプションしかありません。 このため、コードをマージする準備ができるまで、またはコミッターが自分でコードを終了するのに十分な距離になるまで、プルリクエストを行うことは役に立ちません。
ブランチのリベース
上記の例では、「Fixedticket_xxxxx」コミットと「さらに2つのテストを追加」コミットの2つのコミットを作成しました。
作業プロセスの履歴全体をリポジトリに保存する必要はありません。 「さらに2つのテストを追加しました」というコミットは、役に立たないノイズになります。 代わりに、すべての作業を含むコミットを1つだけにします。
ブランチの履歴を作り直すには、インタラクティブなリベースを使用してコミットを1つにまとめることができます。
git rebase -i HEAD~2
上記のHEAD〜2は、最新の2つのコミットの省略形です。 上記のコマンドは、「pick」という単語が前に付いた2つのコミットを表示するエディターを開きます。
代わりに、2行目の「pick」を「squash」に変更してください。 これにより、最初のコミットが維持され、2番目のコミットが最初のコミットに押しつぶされます。 エディターを保存して終了します。 2番目のエディターウィンドウが開くはずです。これで、両方のステップが含まれるようになったので、コミットのコミットメッセージを言い換えることができます。
リベースで「編集」オプションを使用することもできます。 このようにして、単一のコミットを変更できます。たとえば、docstringのタイプミスを修正できます。
git rebase -i HEAD~3
# Choose edit, pick, pick for the commits
# Now you are able to rework the commit (use git add normally to add changes)
# When finished, commit work with "--amend" and continue
git commit --amend
# Reword the commit message if needed
git rebase --continue
# The second and third commits should be applied.
トピックブランチがすでにGitHubで公開されている場合、たとえば、レビューを考慮して小さな変更を加える場合は、変更を強制的にプッシュする必要があります。
git push -f origin ticket_xxxxx
これにより、ticket_xxxxxの履歴が書き換えられることに注意してください。GitHubでの操作の前後にコミットハッシュを確認すると、コミットハッシュが一致しなくなっていることがわかります。 ブランチはトピックブランチであり、誰もそれに基づいて作業するべきではないため、これは許容されます。
アップストリームが変更された後
アップストリーム(django/django
)が変更された場合は、作業をリベースする必要があります。 これを行うには、次を使用します。
git fetch upstream
git rebase
作業は、フォークしたブランチを使用して自動的にリベースされます。この例では、upstream/master
を使用しています。
rebaseコマンドは、すべてのローカルコミットを一時的に削除し、アップストリームコミットを適用してから、作業にローカルコミットを再度適用します。
マージの競合がある場合は、それらを解決してからgit rebase --continue
を使用する必要があります。 いつでもgit rebase --abort
を使用して元の状態に戻すことができます。
アップストリームをマージするのではなく、アップストリームでリベースすることに注意してください。
これは、リベースすることにより、コミットが常にアップストリームの作業の上にあり、がアップストリームの変更と混合されるのではないためです。 このようにすると、ブランチにはそのトピックに関連するコミットのみが含まれるため、押しつぶしが簡単になります。
レビュー後
レビューアからの変更を要求せずに、重要な量のコードをコアに取り込むことは珍しいことです。 この場合、作業への1つの増分コミットとして変更を追加することをお勧めします。 これにより、レビュー担当者はあなたが行った変更を簡単に確認できます。
この場合、レビュー担当者が必要とする変更を行います。 必要に応じて何度でもコミットします。 変更を公開する前に、作業のベースを変更してください。 2つのコミットを追加した場合は、次のように実行します。
git rebase -i HEAD~2
2番目のコミットを最初のコミットに押しつぶします。 次の行に沿ってコミットメッセージを記述します。
Made changes asked in review by <reviewer>
- Fixed whitespace errors in foobar
- Reworded the docstring of bar()
最後に、作業をGitHubリポジトリにプッシュバックします。 リベース中にパブリックコミットに触れなかったので、強制的にプッシュする必要はありません。
git push origin ticket_xxxxx
これで、プルリクエストに新しいコミットも含まれるはずです。
コミッターは、コードをコミットするときに、レビューコミットを前のコミットに押しつぶす可能性が高いことに注意してください。
パッチに取り組んでいます
開発者がDjangoに貢献できる方法の1つは、パッチを確認することです。 これらのパッチは通常、GitHubにプルリクエストとして存在し、ローカルリポジトリに簡単に統合できます。
git checkout -b pull_xxxxx upstream/master
curl https://github.com/django/django/pull/xxxxx.patch | git am
これにより、新しいブランチが作成され、プルリクエストからの変更がブランチに適用されます。 この時点で、テストを実行するか、パッチの品質を調査するために必要なその他のことを行うことができます。
プルリクエストの操作の詳細については、コミッターのガイドラインを参照してください。
概要
- 可能であれば、GitHubで作業してください。
- GitHubブランチにリンクして、Tracチケットでの作業を発表します。
- 準備ができたら、プルリクエストを行います。
- プルリクエストをできる限り適切に行います。
- 作業を修正するときは、
git rebase -i
を使用してコミットを潰してください。 - アップストリームが変更された場合は、
git fetch upstream; git rebase
を実行します。