From 49de83f28a0ca0866e36b612a5186594cae7c347 Mon Sep 17 00:00:00 2001 From: Suvayu Ali Date: Sun, 21 Jun 2020 00:43:34 +0200 Subject: [PATCH 1/4] ARROW-4429: add git conventions to contributing guidelines --- docs/source/developers/contributing.rst | 46 +++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/docs/source/developers/contributing.rst b/docs/source/developers/contributing.rst index 3fea3b85bd6..746ff8c0cc6 100644 --- a/docs/source/developers/contributing.rst +++ b/docs/source/developers/contributing.rst @@ -127,3 +127,49 @@ To contribute a patch: * Add new unit tests for your code. Thank you in advance for your contributions! + +Common Git conventions followed within the project +-------------------------------------------------- + +If you are tracking the Arrow source repository locally, following some common Git +conventions would make everyone's workflow compatible. These recommendations along with +their rationale are outlined below. + +It is strongly discouraged to use a regular ``git merge``, as a linear commit history is +prefered by the project. It is much easier to maintain, and makes for easier +``cherry-picking`` of features; useful for backporting fixes to maintenance releases. +To sync your local copy of a branch, you may do the following:: + + $ git pull upstream branch --rebase + +This will rebase your local commits on top of the tip of ``upstream/branch``. In +case there are conflicts, and your local commit history has multiple commits, you may +simplify the conflict resolution process by squashing your local commits into a single +commit. If you choose this route, you can abort the merge with:: + + $ git merge --abort + +Following which, the local commits can be squashed interactively by running:: + + $ git rebase --interactive ORIG_HEAD + +After the squash, you can try the merge again, and this time conflict resolution should +be relatively straightforward. + +Once you have an updated local copy, you can push to your remote repo. Note, since your +remote repo still holds the old history, you would need to do a force push. :: + + $ git push --force origin branch + +Note about force pushing to a branch that is being reviewed: if you want reviewers to +look at your updates, please ensure you comment on the PR on GitHub as simply force +pushing does not trigger a notification in the GitHub API. + +Simplifying ``rebase`` +++++++++++++++++++++++ + +If you set the following in your repo's ``.git/config``, the ``--rebase`` option can be +ommitted from the ``git pull`` command, as it is implied by default. :: + + [pull] + rebase = true From fa5d9ddf135204f6ca3d9ec7ec6e29c5ccd50899 Mon Sep 17 00:00:00 2001 From: Suvayu Ali Date: Sun, 21 Jun 2020 10:02:16 +0200 Subject: [PATCH 2/4] minor clarification in the wording --- docs/source/developers/contributing.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/source/developers/contributing.rst b/docs/source/developers/contributing.rst index 746ff8c0cc6..3f4038075a3 100644 --- a/docs/source/developers/contributing.rst +++ b/docs/source/developers/contributing.rst @@ -142,10 +142,12 @@ To sync your local copy of a branch, you may do the following:: $ git pull upstream branch --rebase -This will rebase your local commits on top of the tip of ``upstream/branch``. In -case there are conflicts, and your local commit history has multiple commits, you may +This will rebase your local commits on top of the tip of ``upstream/branch``. In case +there are conflicts, and your local commit history has multiple commits, you may simplify the conflict resolution process by squashing your local commits into a single -commit. If you choose this route, you can abort the merge with:: +commit. In the long run preserving the history isn't as important, because when your +feature branch is merged upstream a squash happens automatically. If you choose this +route, you can abort the merge with:: $ git merge --abort @@ -161,9 +163,9 @@ remote repo still holds the old history, you would need to do a force push. :: $ git push --force origin branch -Note about force pushing to a branch that is being reviewed: if you want reviewers to +*Note about force pushing to a branch that is being reviewed:* if you want reviewers to look at your updates, please ensure you comment on the PR on GitHub as simply force -pushing does not trigger a notification in the GitHub API. +pushing does not trigger a notification in the GitHub user interface. Simplifying ``rebase`` ++++++++++++++++++++++ From 2db903150292f53dac49bb2087ab3b482f1fadf9 Mon Sep 17 00:00:00 2001 From: Suvayu Ali Date: Mon, 22 Jun 2020 11:22:44 +0200 Subject: [PATCH 3/4] contributing.rst: fix mistake in `git rebase` command --- docs/source/developers/contributing.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/source/developers/contributing.rst b/docs/source/developers/contributing.rst index 3f4038075a3..7bc5c00a1ec 100644 --- a/docs/source/developers/contributing.rst +++ b/docs/source/developers/contributing.rst @@ -153,10 +153,11 @@ route, you can abort the merge with:: Following which, the local commits can be squashed interactively by running:: - $ git rebase --interactive ORIG_HEAD + $ git rebase --interactive ORIG_HEAD~n -After the squash, you can try the merge again, and this time conflict resolution should -be relatively straightforward. +Where ``n`` is the number of commits you have in your local branch. After the squash, +you can try the merge again, and this time conflict resolution should be relatively +straightforward. Once you have an updated local copy, you can push to your remote repo. Note, since your remote repo still holds the old history, you would need to do a force push. :: From 3b316e160655dcc51780fd9116526658c28479e0 Mon Sep 17 00:00:00 2001 From: Suvayu Ali Date: Mon, 22 Jun 2020 12:11:26 +0200 Subject: [PATCH 4/4] contributing.rst: fix mistake in abort command Since `git pull --rebase` is being called earlier, the abort command should be `git rebase --abort`, instead of the usual. --- docs/source/developers/contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/developers/contributing.rst b/docs/source/developers/contributing.rst index 7bc5c00a1ec..e2a543646e7 100644 --- a/docs/source/developers/contributing.rst +++ b/docs/source/developers/contributing.rst @@ -147,9 +147,9 @@ there are conflicts, and your local commit history has multiple commits, you may simplify the conflict resolution process by squashing your local commits into a single commit. In the long run preserving the history isn't as important, because when your feature branch is merged upstream a squash happens automatically. If you choose this -route, you can abort the merge with:: +route, you can abort the rebase with:: - $ git merge --abort + $ git rebase --abort Following which, the local commits can be squashed interactively by running::