変更管理

このドキュメントは、読者がすでに git を使用してファイルのバージョン管理に精通していることを前提としています。

始める

GROMACS の開発は、gitlabで https://gitlab.com/gromacs/gromacs に行われます。ユーザーアカウントを作成するには、https://gitlab.com/users/sign_in#register-pane にアクセスするか、gitlab.com で既存のアカウントを使用します。gitlab の使用方法については、https://docs.gitlab.com/ee/user/index.html での詳細なユーザードキュメントを参照してください。

もし、すでに GROMACS リポジトリが設定されていない場合は、git clone git@gitlab.com:gromacs/gromacs.git を使用して、gitlab から現在の GROMACS リポジトリを取得してください。それ以外の場合は、git remote add gitlab git@gitlab.com:gromacs/gromacs.git を使用してください。

GitLabを使用すると、新しいコードは、開発ブランチをメインブランチにマージすることで、|Gromacs|に統合されます。

新しいコードに潜む問題を自動的に検出するために、広範な設定の組み合わせを使用して継続的インテグレーション (CI) でテストを行います。 自動ソースコードフォーマット を参照して、スタイルガイドへの準拠を確認し、テストを実行してください。

変更管理に関する詳細情報は、gitlab wiki で確認できます。

GitLabでのログイン資格設定

You will need a public ssh key:

ssh-keygen -t rsa -C "your.email@address.com"
cat ~/.ssh/id_rsa.pub

最後に実行したコマンドの出力をコピーし、gitlab.com にアクセスして、パネルの右上にある自分のユーザーシンボルをクリックし、「設定」を選択します。

左側のメニューからSSHキーを選択し、テキストフィールドにキーを貼り付けてください。

問題の作成

メタレベルのコード設計と議論は、issueとして整理されており、https://gitlab.com/gromacs/gromacs/-/issues で確認できます。新しいissueを作成する前に、ご自身のissue、または類似のissueが既に存在するかどうかを確認してください。詳細については、有意義な問題報告を作成するためのガイドライン を参照してください。

注意: すべてのRedmineの問題は、元のRedmineの問題番号を保持したまま、gitlabに移行されています。ただし、コメントと議論は、gitlabユーザー`@acmnpv <https://gitlab.com/acmnpv>`によって行われており、元の作成者はコメントの末尾に記載されています。

コードのアップロードとレビュー - マージリクエストの作成

問題は、新しいコードを使用して「マージリクエスト」 (MR) を通じて解決されます。現在の MR は、https://gitlab.com/gromacs/gromacs/-/merge_requests で確認できます。マージリクエストを作成する方法は 2 つあります。どちらか一方を、グラフィカルユーザーインターフェースまたはコマンドライン経由で実行できます。

GUIを使用するには、関連する問題を検索するか、新しい問題を新規作成し、「マージリクエストの作成」ボタンを見つけて、GitLabでその問題に関連するマージリクエストを作成します。コードを完全に確認し、すべてのテストがパスしているまで、「ドラフトとしてマーク」オプションを使用することを推奨します。

進捗状況の追跡を容易にするために、マイルストーンと担当者を選択してください。マージに関する要件は、デフォルト設定で維持されます。

また、コマンドラインで git push を直接使用して、コマンドラインで出力されるリンクを使用してマージリクエストを作成することもできます。

リポジトリは、|Gromacs|のリポジトリと同期している必要があります。これを確実にするには、最新のブランチを取得するために git fetch を使用し、次に、自分のブランチ上で git merge main を実行して、メインブランチを自分のブランチにマージします。

「Developer」の役割を持つアカウントは不要ですが、MRのテストパイプラインを開始するには、プロジェクトのメンバーであり（少なくとも）「Developer」の役割を持つ必要があります。プロジェクトへの参加は、Gitlabのウェブインターフェースを通じてリクエストできます。「Developer」の役割は、プロジェクトへの貢献意図に関する知識や経験に基づいて付与されます。

上記：ref:`コードレビュー`で述べたように、「開発者」の役割は、「GMX 開発者」承認グループへの参加とは異なります。「変更の承認とマージには、開発者としてカウントされるのに必要な権限よりも高い権限が必要です。

ブランチの名前を付ける

良い名前の例：documentation_UpdateDevelopersDocsTOGitLab、nbnxm_MakeNbnxmGPUIntoClass、pme_FEPPMEGPU、1234-ml-fix-issue。

悪い名前の例：branch1234、mybranch、testなど

注：ブランチ名の先頭に issue 番号（例：1234-ml-fix-issue のように）とハイフンを付けると、自動的にブランチを issue に関連付けます。マイルストーンとラベルはコピーされ、MR がマージされると issue が閉じられます。詳細については、GitLab のドキュメント を参照してください。

ドキュメント

貢献者とレビュー者は、変更の影響が生成されたドキュメントに及ぼす影響を頻繁に考慮していません。 貢献者とレビュー者は、自動テストジョブからの生成されたドキュメントは、GitLab CIのWebインターフェース（``webpage:build``ジョブの成果物）を通じてダウンロードできることを認識する必要があります。 より早いレビューや代替の選択肢については、生成されたドキュメントを含むDockerイメージを構築して共有することを検討してください。 ソースツリー内の docs/docs.dockerfile を参照してください。

ラベル

ラベル は、開発者が問題とマージリクエストをさらに絞り込むことを可能にし、役立ちます。

プロジェクト「Gromacs」は、<https://gitlab.com/gromacs/gromacs/-/labels> のように、多くのラベルを定義しています。

重複したドキュメントを減らすために、ラベルの説明については、GitLab プロジェクトのラベル のウェブインターフェースを参照してください。

新しいラベルを作成する際は、ラベルが何を意図しているのか、また、自分自身の問題やマージリクエストに適用する際にいつ使用すべきかを理解できるように、簡単な説明を提供してください。

一般的な場合：

  • 現在行われている分類は、|Gromacs|のコンポーネントまたは開発領域を特定するために使用され、その際には``#7F8C8D``の色が用いられます。

  • 特定の機能またはサブプロジェクト領域で、今後のリリースを対象としている場合は、「#8E44AD」の背景色を使用します。

  • ステータスラベルには「#428BCA」を使用します。ステータスラベルは、Issueにも使用され、:ref:`ステータスラベルのガイドライン <status label guidelines>`に従って使用されます。

コードレビュー

他人のアップロードしたコードのレビュー

レビューのワークフローは以下のとおりです。

  1. https://gitlab.com/gromacs/gromacs/-/merge_requests は、すべての未完了の変更を表示します。

  2. 変更を反映させるには、2つの承認が必要です。そのうち1つの承認は、「GMX Core」または「GMX Developers」の承認グループのいずれかのメンバーから得られる必要があります。

  3. 通常、パッチは、開発者の投票、コメント、および更新の複数のサイクルを経て、承認されるまでに、開発者の投票によって、変更が十分に進んでいるかどうかを示すことが必要です。

  4. 変更をマージし、マージ後にテストするために、「マージ」をクリックします。

ご自身のコードをレビューしないでください。このポリシーの目的は、少なくとも2人の非著者によって承認を得ること、および承認者がマージ前に問題を解決することです。もし、他の人のパッチに修正をアップロードした場合、ご自身で承認するかどうかは、ご自身の判断で決定してください。

「GMX Developers」および「GMX Core」の承認グループへの参加は、プロジェクトへの長期間の貢献に基づいて決定され、これは「Developer」ロールのユーザーアカウントとは直接的な関連性はありません。

レビューのガイド

  • 最も重要なことは、可能な限り、内容の正確性を確認することです。

  • 移植性とパフォーマンスが最も重要な要素であるため、潜在的な問題がないか確認してください。

  • コーディング規約：ref:コーディング規約 に準拠しているか確認してください。

  • 私たちは、バグ修正（および重要な機能やタスクを実装する）を行うコミットが、`issue tracker`へのエントリが作成され、リンクされるように努めるべきです。このリンクは、`<https://gitlab.com/help/user/markdown#special-gitlab-references>`の特別な構文を通じて**自動的に**行われます。

  • もしコミットが**バグ修正**である場合：

    • もし、`issue tracker`に存在する場合、有効な参照を含む必要があります。

    • もし、それが**重大なバグ**である場合、issue tracker でバグ報告書を提出し、適切な形で参照する必要があります（緊急度または最優先度で）。

  • コミットが**機能/タスク**の実装の場合：

    • もし、それが issue tracker に存在する場合は、有効な参照を含む必要があります。

    • 現在、特定の課題が存在しない場合、および変更が将来の理由の説明に役立つ場合、新しい課題を作成する必要があります。

ステータスラベルを更新する

  • マージリクエストがレビュー中の場合は、ステータスラベルを必ず <issue workflow> の状態に更新してください。

  • マージリクエストが完了したら、「ステータス」ラベルを必ず更新してください。

マージリクエストの完了

6か月以上更新がないマージリクエストは、「ステータス::古い」というステータスラベルを取得する可能性があります。提案された変更が依然として重要であり、次のステップが不明な場合、古い状態の問題を持つ貢献者は…

  • 既存のレビュー担当者（または潜在的なレビュー担当者）に連絡を取るため、

  • 参加するために、`開発者フォーラム`に参加し、

  • 会議に参加して、連携を調整するために、隔週の電話会議に参加してください。

もし、マージリクエストの将来が1ヶ月以内に明確になっていない場合（特に、複数回「ステータスが変更」された場合）、開発者は、リクエストが「完了」状態になった理由を示すラベルを追加して、マージリクエストをクローズすることができます。「Status::MR::..."ラベル <https://gitlab.com/gromacs/gromacs/-/labels?subscribed=&search=status%3A%3Amr>」は、リクエストが明示的に拒否されていない限り、マージリクエストがレビューされたことを示しません。

詳細については、issue：4126 を参照してください。

  • Status::MR::Inactive: 貢献者からの返信がない場合、またはレビュー担当者が6ヶ月以上利用できない場合。

  • Status::MR::Superseded: このマージリクエストは不要になりました。

  • Status::MR::Rejected: 提案（または関連する問題）は採用されません。

  • Status::MR::議論が必要: MR を作成する前に、追跡されている issue でさらに議論を行う必要があります。

  • Status::Stale: 6か月以上のアクティビティがない。

参考

Issueワークフロー におけるステータスラベルの使用に関する情報。

さらにGitのヒント

Q: 他にも便利なGitの設定はありますか？

A: もし、大きな差分（特に、多くのファイルが移動されている場合）を持つブランチと作業する必要がある場合は、以下の設定を行うことが役立つ場合があります。

git config diff.renamelimit 5000

Git が考慮する、近似的なリネームの制限を増やすため。デフォルト値では不十分な場合、例えば、メインブランチからリリースブランチへのマージやチェリーピックを行う必要がある場合に有効です。

Q: git rebase (または git pull --rebase) をどのように使用しますか？

A: 以下の前提条件を仮定します。 * ローカルの機能ブランチがチェックアウトされている。 * そのブランチは main ブランチをベースにしている。 * main ブランチに新しいコミットが追加されている。

git rebase main

メインブランチの最新コミットの上に、自分のコミットを適用します。これにより、これまで行ったすべてのコミットを保存し、メインブランチの上に再適用できます。もしコミットで競合が発生した場合は、通常の手順で解決する必要があります（`git add`を使用して解決をマークするなど）。

git rebase --continue

注意：もしあなたが何をしようとしているのか確信がない場合は、コミットを作成または削除するコマンド（git commit、git checkout、またはパスを指定せずに git reset）を使用しないでください。git rebase --continue は、競合が解決された後にコミットを作成し、元のコミットメッセージ（編集する機会も提供されます）を使用します。

もし、解決が困難なほど混乱している競合（または、混乱を引き起こした誤りが見つかった場合）、以下の方法を使用できます。

git rebase --abort

元の git rebase main コマンドを実行した状態に戻るには（つまり、リベースを開始する前の状態に戻る）。もしリベースがすでに完了しており、誤った操作をしたことに気づいた場合は、( git log <my-branch>@{1} および/または git reflog を使用して、これが目的の状態であることを確認しながら) 以前の状態に戻ることができます。

git reset --hard <my-branch>@{1}

Q: 複数のコミットをまとめて作成するにはどうすればよいですか？

A: 複数の独立した変更をワークツリーに適用することを想定しています。

git add [-p] [file]

個別の変更を1つずつインデックスに追加するために、以下の手順を使用します。

git diff --cached

変更内容がインデックスに含まれていることを確認できます。その後、この変更をコミットできます。

git commit

もし、変更が正常に機能しているかどうかを確認したい場合は、他の変更を一時的に保存し、その上でテストを実行してください。

git stash

テストが失敗した場合、「git commit --amend」を使用して既存のコミットを修正できます。 修正後、レビューのためにコミットをプッシュできます。 変更を一時保存した場合で、次の変更を独立してレビューしたい場合は、

git reset --hard HEAD^
git stash pop

(以前の変更をリポジトリにプッシュした場合のみ実行してください。そうでない場合、以前の変更を復元することが困難になります！) そして、各独立した変更を個別のコミットにまで繰り返してください。 git reset --hard のステップをスキップした場合、変更を基にしたローカルな機能ブランチを作成することも可能です。

Q: 以前のコミットを編集するにはどうすればよいですか？

A: 最新のコミットを編集したい場合は、必要な変更を加えるだけで済みます。

git commit --amend

もし、別のコミットを編集したい場合で、そのコミット以降のコミットで同じ行が変更されていない場合は、通常の手順で変更を行い、

git commit --fixup <commit>

または

git commit --squash <commit>

ここで <commit> は、変更したいコミットを指定します（--fixup は元のコミットメッセージを保持しますが、--squash は追加のメモを入力し、git rebase -i で元のコミットメッセージを編集できるようにします）。この方法で複数のコミットを実行できます。また、--fixup / --squash コミットを通常のコミットと組み合わせて使用することも可能です。 完了したら、次のコマンドを使用します。

git rebase -i --autosquash <base-branch>

「--fixup/--squash」コミットを修正するコミットにマージするために、git rebase -i を使用して、どのブランチをベースとして使用するかを選択する方法については、別のドキュメントを参照してください。

このようなワークフローでは、同じ行を複数のコミットで変更することを避けるようにしてください（ただし、``--fixup/--squash``のコミットを除く）。しかし、すでにいくつかの行を変更し、以前のコミットを編集したい場合は、以下の方法を使用できます。

git rebase -i <base-branch>

ただし、後でいくつかの競合を解決する必要がある可能性はあります。詳細は後述の「git rebase -i」を参照してください。

Q: どのようにしてコミットを分割しますか？

A: 以下の手順は、HEAD のコミットを分割するために適用されます。上記の手順で git rebase -i を使用して、以前のコミットを HEAD として分割する方法を確認してください。

最も簡単なケースは、コミット A を A'-B-C の連鎖に分割したい場合です。ここで、A' は最初の新しいコミットであり、元のコミットの大部分（コミットメッセージを含む）を含んでいます。この場合、以下の操作を実行できます。

git reset -p HEAD^ [-- <paths>]
git commit --amend

Aコミットから特定の部分を削除し、それらをワークングツリーに残すことができます。その後、残りの変更を1つまたは複数のコミットとして、他のヒントで説明されている方法で作成できます。

もし、コミット A を B-A'-C のような連鎖に分割したい場合で、元のコミットメッセージを最初のコミット以外の目的（例えば、B-A'-C）で使用したい場合は、以下の手順で実行できます。

git reset HEAD^

HEAD のコミットを削除しますが、作業ツリー内のすべての変更を保持します。その後、他の手順で説明されているように、独自のコミットを作成できます。元のコミットメッセージを再利用したい場合に、以下の方法を使用できます。

git reflog

元のコミットを HEAD@{n} として参照する方法については、こちらを参照してください。

git commit -c HEAD@{n}

Q: paikalen コミットのみを編集するために、git rebase -i をどのように使用しますか？

A: 以下の前提条件を考慮してください。 * ローカルの機能ブランチがチェックアウトされており、そのブランチには3つのコミットが含まれており、`main`ブランチをベースにしている。 * `main`ブランチには、あなたがブランチを切った後、さらにいくつかのコミットが追加されている。 * もし、`git rebase -i`を使用して機能ブランチを編集したい（上記を参照）場合、以下の手順を実行する必要がある。

git rebase -i HEAD~3

続いて、別の

git rebase main

最初のコマンドを使用すると、メインブランチの変更による競合を回避しながら、ローカルブランチを編集できます。 2番目のコマンドを使用すると、これらの競合を別のリベース実行で解決できます。 もし自信がある場合は、両方を同時に実行することも可能です。

git rebase -i main