Fork and Branch Git ワークフロー

このドキュメントは、iDempiereのコミットを管理するワークフローを定義しています。(2020年4月30日に開始されました。)

このワークフローは、フォーキングワークフロー("Forking Workflow")もしくは、フォーク&ブランチ Git ワークフローとして知られています。 このワークフローについては、グーグルで検索する事で、より良い情報を得られるでしょう。

このドキュメントでは、iDempiereにおいてどのように行うのか説明しています。

フォークしてリポジトリを作成する

iDempiereプロジェクトに貢献するすべての開発者は、iDempiereのリポジトリからフォークした自分のリポジトリを作成することが奨励されています。

フォークするのはとても簡単です。下記のURLにアクセスして、"Fork"ボタンを押すだけです。:
https://github.com/idempiere/idempiere

そうするとフォークして、あなた個人のアカウントにそのリポジトリを作成します。

ソースコードをローカルにクローンする

フォークしたあなた個人のリポジトリにあるソースコードをクローンして、あなたのPCにコピーします。 クローンするのは、下記のコマンドを実行するだけです。:

git clone https://github.com/(your-github-user)/idempiere.git

NOTE: あたなが公式のiDempiereリポジトリより既にクローンしている場合、完全にクローンする代わりに、クローンしたフォルダに移動して下記のコマンドを実行することができます。

git remote remove origin
git remote add origin https://github.com/(your-github-user)/idempiere.git

そうすると、公式のiDempiereリポジトリが、"upstream"となります。

git remote add upstream https://github.com/idempiere/idempiere.git
git branch --set-upstream-to=origin/master master

正しい設定がされていることを確認するには…

git remote -v

…で、以下のような出力が表示されるはずです。:

origin	git@github.com:hengsin/idempiere.git (fetch)
origin	git@github.com:hengsin/idempiere.git (push)
upstream	https://github.com/idempiere/idempiere.git (fetch)
upstream	https://github.com/idempiere/idempiere.git (push)

そして、Installing iDempiere で説明したように、開発環境の設定を行います。

Asking for a pull request

upstreamとの同期

PCにクローンしたソースコードがマスターリポジトリと同期していることを常に確認する必要があります。:

git checkout master
git pull upstream master
git push origin master

特定の機能専用のブランチの作成

すべてのコミットは、特定のチケットのために作成されたブランチで行わなければなりません。:

解決しようとしている JIRAのチケット用のブランチを作成する:

git checkout -b IDEMPIERE-(Jira-ticket-number)

パッチの開発もしくは適用

その後、パッチを開発したり、ピアレビューされているパッチを適用したりすることができます。

通常のパッチの当て方は次の通りです:

• normal patch format (f.e. coming from mercurial)

git apply (patch-file)

• patches in git format are normally created using the instruction "git format-patch -1 --stdout (commit) > (patch-file)", these patches can be imported using:

git am --keep-cr (patch-file)

TEST!

コミットする前に必ずテストを実施し、テストされていないコードは絶対にコミットしないようにしなければなりません (真面目な話、あなたの評判は悪くなります)。

変更内容をテストし、さらに重要なことは、変更したコードの照合を常にチェックし、影響を受ける他のユースケースを把握し、それらもテストすることです!

Commit

すべてのテストに問題がなければ、変更したファイルをステージに追加します。

git add .

そしてコミットします。ここでは2つの重要なことがあります。:

• GitHubに登録したメールのいずれかを使用します。
• コミットのメッセージに右記のようにJiraのチケット番号を含めるようにします。 IDEMPIERE-(Jira-ticket-number)
• if your commit resolves completely the JIRA ticket you can add the smart commit message #resolve
• また、チケットに最後のコメントを追加することもできます。 #comment (your-final-comment-for-ticket)

git commit

Push

コミットを自分のフォークにプッシュしてください。:

git push

うまくいかない場合は、以下を試してみてください。

git push origin IDEMPIERE-(Jira-ticket-number) [your branch]

Pull request

そして、ブラウザでコンソール出力に表示されているURLに移動します。:
https://github.com/globalqss/idempiere/pull/new/IDEMPIERE-(Jira-ticket-number)

そこに適切なメッセージを書き、変更の影響、ユースケースやその他のユースケースの影響、行ったテストの説明をします。
影響やテストの方法についての情報が多ければ多いほど、査読者が変更を受け入れやすくなります。
そして、"Create pull request "ボタンを押してリクエストを送信します。

Changing a pull request

Adding more commits

ピアレビュアーのリクエストがプルリクエスト上で変更された場合、変更を行って新しいコミットをリポジトリにプッシュするだけで、githubはそれに応じてプルリクエストを自動的に更新します。

Editing the commit message

コミットメッセージには常にそれを解決する JIRA チケットが含まれていなければなりません (また、スマートコミットメッセージを使って自動的に解決することもできます。このルールに従うためにコミットメッセージを修正するように要求された場合、次のコマンドを使って最後のコミットのメッセージを編集することができます (古いコミットメッセージを編集する可能性があります。):

git checkout -b IDEMPIERE-(Jira-ticket-number)
git commit --amend
git push --force-with-lease

Approving a pull request

私たちのワークフローは、コア開発者（依頼元とは異なる）の承認を最低1回は必要とするように構成されています。

レビュー者はプルリクエストのリンク先にアクセスして、小さなコミットであればそこの指示に従うことができます。コードピアレビューは多分十分です、それが大きな変更である場合は、ローカルテストを実施することをお勧めします、プルリクエストをローカルでテストする方法についてのGitHubの指示があります。

このプロセスでは、プルリクエストを承認したり、変更を要求するコメントをつけたり、拒否したりすることができます。

After approval

コミットを承認したコア開発者は通常、コードを公式マスターに統合するために「Squash and merge」というボタンを押します。

その後、変更を再度上流から引っ張ってくることができます。:

git checkout master
git pull upstream master

変更をあなたのフォークしたリポジトリにプッシュして下さい。:

git push origin master

そして、ローカルで一時的に作成したブランチを削除します。:

git branch -d IDEMPIERE-(Jira-ticket-number)

And delete your temporary feature branch on the remote repository (NOTE this is not required if you your repository setting "Automatically delete head branches" is set to true):

git push origin --delete IDEMPIERE-(Jira-ticket-number)

And finally, resolve the JIRA ticket if the development is complete (this step is not required if you used smart commit message as explained above).

Tips:

if your local working directory have changes that you need to temporarily put aside, git stash is a very useful tool for that.

Avoid committing to master

To avoid committing by mistake to the master branch you can create the file .git/hooks/pre-commit with the following content:

#!/bin/sh
branch="$(git rev-parse --abbrev-ref HEAD)"
if [ "$branch" = "master" ]; then
  echo "You can't commit directly to master branch"
  exit 1
fi

And then make the file executable:

chmod +x .git/hooks/pre-commit

Summary

要約すると、コミットがリポジトリ間を移動する方法は次のようになります。:

• local: push to origin feature branch
• github: pull request to the upstream master
• github: approve
• github: merge to upstream master
• local: pull it back from upstream
• local: push back to your origin master