コミットコード—Djangoドキュメント

コミットコード

このセクションは、コミッショナーと、コードがDjangoにコミットされる方法を知りたい人を対象としています。 Djangoにコードを提供したいコミュニティメンバーの場合は、代わりに GitとGitHubの操作をご覧ください。

プルリクエストの処理

DjangoはGitHubでホストされているため、パッチはプルリクエストの形式で提供されます。

プルリクエストをコミットするときは、個々のコミットが以下に説明するコミットガイドラインに一致していることを確認してください。 コントリビューターは、可能な限り最高のプルリクエストを提供することが期待されています。 ただし、実際には、コミットガイドラインに精通している可能性が高いコミッターは、コミットを標準に引き上げることを決定する場合があります。

OracleやSeleniumなど、自動的に実行されないプルリクエストビルダーの1つを使用して、Jenkinsにプルリクエストをテストさせることができます。 手順については、 Jenkinswikiページを参照してください。

ローカルでプルリクエストをより頻繁にチェックアウトしていることに気付いた場合は、このgitエイリアスが役立ちます。

[alias]
    pr = !sh -c \"git fetch upstream pull/${1}/head:pr/${1} && git checkout pr/${1}\"

それを~/.gitconfigに追加し、upstreamをdjango/djangoに設定します。 次に、git pr ####を実行して、対応するプルリクエストをチェックアウトできます。

この時点で、コードで作業できます。 git rebase -iおよびgit commit --amendを使用して、コミットが期待されるレベルの品質であることを確認します。 準備ができたら：

メインにリベースした後、マージしてアップストリームにプッシュする前に、ブランチに強制的にプッシュします。 これにより、メインとブランチのコミットハッシュが一致し、プルリクエストが自動的に閉じられます。

プルリクエストを複数のコミットとしてマージする必要がない場合は、ウェブサイトのGitHubの[スカッシュしてマージ]ボタンを使用できます。 ガイドラインに準拠するように必要に応じてコミットメッセージを編集し、メッセージの最初の行に自動的に追加されるプルリクエスト番号を削除します。

プルリクエストのコミット履歴を書き換えるときの目標は、Djangoのコミット履歴を可能な限り使用できるようにすることです。

• パッチに前後のコミットが含まれている場合は、それらを1つに書き直します。 たとえば、コミットによってコードが追加され、2番目のコミットで最初のコミットで発生したスタイルの問題が修正された場合、それらのコミットはマージする前に潰す必要があります。
• 論理グループ化によって異なるコミットへの変更を分離します。ファイルに他の変更を行うと同時にスタイルのクリーンアップを行う場合、変更を2つの異なるコミットに分割すると、履歴の確認が容易になります。
• プルリクエストでのアップストリームブランチのマージに注意してください。
• テストに合格し、各コミット後にドキュメントを作成する必要があります。 テストもドキュメントも警告を発するべきではありません。
• 些細で小さなパッチは通常、1回のコミットで行うのが最適です。 中規模から大規模の作業は、意味がある場合は複数のコミットに分割できます。

実用性は純粋さよりも優れているため、プルリクエストに対してどの程度の履歴マングリングを行うかを決定するのは各コミッター次第です。 主なポイントは、コミュニティとの関わり、仕事の遂行、および使用可能なコミット履歴の保持です。

コミットメントガイドライン

さらに、DjangoのGitリポジトリにコードをコミットするときは、次のガイドラインに従ってください。

• django/djangoブランチの公開履歴を無理に押して変更しないでください。 どうしても必要な場合（セキュリティ上の理由など）は、最初にチームと状況について話し合ってください。

• 「中から大」があなたの判断による中規模から大規模の変更については、変更を行う前に django-developers メーリングリストに物事を提示してください。

  django-developers で何かを取り上げても誰も応答しない場合は、それをあなたのアイデアが素晴らしいとは思わないでください。誰も異議を唱えなかったので、すぐに実装する必要があります。 誰もがメーリングリストのディスカッションをすぐに読む時間が常にあるとは限らないため、応答を得るまでに数日待たなければならない場合があります。

• 現在形ではなく、過去形で詳細なコミットメッセージを記述します。

  • 良い例：「RSSAPIのUnicodeバグを修正しました。」

  • 悪い例：「RSSAPIのUnicodeバグを修正しました。」

  • 悪い例：「RSSAPIのUnicodeバグを修正しました。」

  コミットメッセージは、最大72文字の行にする必要があります。 空白行と72文字行の段落で区切られた件名が必要です。 限界は柔らかいです。 件名は短い方が良いです。 コミットメッセージの本文では、詳細は少ないよりも優れています。

  Fixed #18307 -- Added git workflow guidelines.
  
  Refactored the Django's documentation to remove mentions of SVN
  specific tasks. Added guidelines of how to use Git, GitHub, and
  how to use pull request together with Trac instead.

  コミットメッセージで寄稿者の功績を認めてください：「報告してくれたAとレビューしてくれたBに感謝します。」 必要に応じて、gitの Co-Authored-By を使用してください。

• ブランチへのコミットの場合、コミットメッセージの前にブランチ名を付けます。 例：「[1.4.x]修正＃xxxxx –マインドリーディングのサポートが追加されました。」

• Limitは、意味のある最も詳細な変更にコミットします。 つまり、頻繁に発生する大きなコミットではなく、頻繁に発生する小さなコミットを使用します。 たとえば、機能Xを実装するためにライブラリYに小さな変更が必要な場合は、最初にライブラリYに変更をコミットしてから、別のコミットで機能Xをコミットします。 これは、すべての人があなたの変更をフォローするのを助けるのに長い道のりになります。

• バグ修正と機能変更を分けてください。 サポートされているバージョンによると、バグ修正を安定版ブランチにバックポートする必要がある場合があります。

• コミットがDjango チケットトラッカーでチケットを閉じる場合は、「Fixed＃xxxxx」というテキストでコミットメッセージを開始します。「xxxxx」は、コミットで修正されたチケットの番号です。 例：「修正＃123 –whizbang機能を追加しました。」 その形式のコミットメッセージが参照されたチケットを自動的に閉じ、完全なコミットメッセージとともにコメントを投稿するようにTracを装備しました。

  不思議なことに、これには Tracプラグインを使用しています。

ノート

Trac統合はプルリクエストについて何も知らないことに注意してください。 したがって、コミットメッセージで「closes＃400」というフレーズを使用してプルリクエストを閉じようとすると、GitHubはプルリクエストを閉じますが、TracプラグインはTracで同じ番号のチケットを閉じません。

• コミットがDjango チケットトラッカーでチケットを参照しているが、はチケットを閉じない場合は、「Refs＃xxxxx」というフレーズを含めます。「xxxxx」はチケットの番号です。参照をコミットします。 これにより、適切なチケットにコメントが自動的に投稿されます。

• 次のパターンを使用して、バックポートのコミットメッセージを記述します。

  [<Django version>] Fixed <ticket> -- <description>
  
  Backport of <revision> from <branch>.

  例えば：

  [1.3.x] Fixed #17028 -- Changed diveintopython.org -> diveintopython.net.
  
  Backport of 80c0cbf1c97047daed2c5b41b296bbc56fe1d7e3 from main.

  これを自動化するためのスクリプトがwiki にあります。

  コミットでリグレッションが修正された場合は、これをコミットメッセージに含めます。

  Regression in 6ecccad711b52f9273b1acb07a57d3f806e93928.

  （回帰が導入されたコミットハッシュを使用します）。

コミットを元に戻す

誰も完璧ではありません。 間違いが犯されます。

しかし、間違いが起こらないように一生懸命努力してください。 返品ポリシーがあるからといって、可能な限り最高の品質を目指すというあなたの責任を緩和することはできません。 本当に：あなたの仕事を再確認するか、最初にそれをコミットする前に他のコミッターにチェックしてもらってください！

誤ったコミットが発見された場合は、次のガイドラインに従ってください。

• 可能であれば、元の作成者に自分のコミットを元に戻してもらいます。
• 元の作成者の許可なしに、別の作成者の変更を元に戻さないでください。
• git revertを使用します–これにより逆コミットが行われますが、元のコミットは引き続きコミット履歴の一部になります。
• 元の作成者に連絡できず（妥当な時間内– 1日程度）、問題が深刻な場合–クラッシュバグ、主要なテストの失敗など。 –次に、 django-developers メーリングリストで異議を唱え、異議がない場合は元に戻します。
• 問題が小さい場合（たとえば、機能がフリーズした後の機能のコミット）、それを待ちます。
• コミッターと将来のリバーターの間に不一致がある場合は、 django-developers メーリングリストで解決してみてください。 合意に達することができない場合は、投票する必要があります。
• コミットによって確認済みの開示されたセキュリティの脆弱性が導入された場合、誰の許可もなしにコミットをすぐに元に戻すことができます。
• リリースブランチのメンテナは、コミットがリリースブランチを壊した場合、許可なくリリースブランチへのコミットを取り消す可能性があります。
• トピックブランチを誤ってdjango/djangoにプッシュした場合は、それを削除してください。 たとえば、git push upstream feature_antigravityを実行した場合は、逆プッシュを実行します：git push upstream :feature_antigravity。