From 321e6422e28651ff5d9ec366d6824e992977ba25 Mon Sep 17 00:00:00 2001 From: Mick Semb Wever Date: Sat, 1 May 2021 16:09:09 +0200 Subject: [PATCH] Update how_to_commit.rst after creating release branch 4.0 patch by Mick Semb Wever; reviewed by Ekaterina Dimitrova for CASSANDRA-16642 --- doc/source/development/how_to_commit.rst | 116 +++++++++++++++++++---- 1 file changed, 96 insertions(+), 20 deletions(-) diff --git a/doc/source/development/how_to_commit.rst b/doc/source/development/how_to_commit.rst index d956c72d8c..d3de9e511c 100644 --- a/doc/source/development/how_to_commit.rst +++ b/doc/source/development/how_to_commit.rst @@ -21,55 +21,131 @@ How-to Commit If you are a committer, feel free to pick any process that works for you - so long as you are planning to commit the work yourself. +Patch based Contribution +------------------------ + Here is how committing and merging will usually look for merging and pushing for tickets that follow the convention (if patch-based): -Hypothetical CASSANDRA-12345 ticket is a cassandra-3.0 based bug fix that requires different code for cassandra-3.3, and trunk. Contributor Jackie supplied a patch for the root branch (12345-3.0.patch), and patches for the remaining branches (12345-3.3.patch, 12345-trunk.patch). +Hypothetical CASSANDRA-12345 ticket is a cassandra-3.0 based bug fix that requires different code for cassandra-3.11, cassandra-4.0, and trunk. Contributor Jackie supplied a patch for the root branch (12345-3.0.patch), and patches for the remaining branches (12345-3.11.patch, 12345-4.0.patch, 12345-trunk.patch). On cassandra-3.0: - #. ``git am -3 12345-3.0.patch`` (if we have a problem b/c of CHANGES.txt not merging anymore, we fix it ourselves, in place) + #. ``git am -3 12345-3.0.patch`` (any problem b/c of CHANGES.txt not merging anymore, fix it in place) + #. ``ant realclean && ant jar build-test`` (rebuild to make sure code compiles) -On cassandra-3.3: +On cassandra-3.11: #. ``git merge cassandra-3.0 -s ours`` - #. ``git apply -3 12345-3.3.patch`` (likely to have an issue with CHANGES.txt here: fix it ourselves, then git add CHANGES.txt) - #. ``git commit —amend`` + #. ``git apply -3 12345-3.11.patch`` (any issue with CHANGES.txt : fix and `git add CHANGES.txt`) + #. ``ant realclean && ant jar build-test`` (rebuild to make sure code compiles) + #. ``git commit --amend`` (Notice this will squash the 3.11 applied patch into the forward merge commit) + +On cassandra-4.0: + #. ``git merge cassandra-3.11 -s ours`` + #. ``git apply -3 12345-4.0.patch`` (any issue with CHANGES.txt : fix and `git add CHANGES.txt`) + #. ``ant realclean && ant jar build-test`` (rebuild to make sure code compiles) + #. ``git commit --amend`` (Notice this will squash the 4.0 applied patch into the forward merge commit) On trunk: - #. ``git merge cassandra-3.3 -s ours`` - #. ``git apply -3 12345-trunk.patch`` (likely to have an issue with CHANGES.txt here: fix it ourselves, then git add CHANGES.txt) - #. ``git commit —amend`` + #. ``git merge cassandra-4.0 -s ours`` + #. ``git apply -3 12345-trunk.patch`` (any issue with CHANGES.txt : fix and `git add CHANGES.txt`) + #. ``ant realclean && ant jar build-test`` (rebuild to make sure code compiles) + #. ``git commit --amend`` (Notice this will squash the trunk applied patch into the forward merge commit) On any branch: - #. ``git push origin cassandra-3.0 cassandra-3.3 trunk —atomic`` + #. ``git push origin cassandra-3.0 cassandra-3.11 cassandra-4.0 trunk --atomic -n`` (dryrun check) + #. ``git push origin cassandra-3.0 cassandra-3.11 cassandra-4.0 trunk --atomic`` + + +Git branch based Contribution +----------------------------- Same scenario, but a branch-based contribution: On cassandra-3.0: - #. ``git cherry-pick `` (if we have a problem b/c of CHANGES.txt not merging anymore, we fix it ourselves, in place) + #. ``git cherry-pick `` (any problem b/c of CHANGES.txt not merging anymore, fix it in place) + #. ``ant realclean && ant jar build-test`` (rebuild to make sure code compiles) -On cassandra-3.3: +On cassandra-3.11: #. ``git merge cassandra-3.0 -s ours`` - #. ``git format-patch -1 `` - #. ``git apply -3 .patch`` (likely to have an issue with CHANGES.txt here: fix it ourselves, then git add CHANGES.txt) - #. ``git commit —amend`` + #. ``git format-patch -1 `` (alternative to format-patch and apply is `cherry-pick -n`) + #. ``git apply -3 .patch`` (any issue with CHANGES.txt : fix and `git add CHANGES.txt`) + #. ``ant realclean && ant jar build-test`` (rebuild to make sure code compiles) + #. ``git commit --amend`` (Notice this will squash the 3.11 applied patch into the forward merge commit) + +On cassandra-4.0: + #. ``git merge cassandra-3.11 -s ours`` + #. ``git format-patch -1 `` (alternative to format-patch and apply is `cherry-pick -n`) + #. ``git apply -3 .patch`` (any issue with CHANGES.txt : fix and `git add CHANGES.txt`) + #. ``ant realclean && ant jar build-test`` (rebuild to make sure code compiles) + #. ``git commit --amend`` (Notice this will squash the 4.0 applied patch into the forward merge commit) On trunk: - #. ``git merge cassandra-3.3 -s ours`` - #. ``git format-patch -1 `` - #. ``git apply -3 .patch`` (likely to have an issue with CHANGES.txt here: fix it ourselves, then git add CHANGES.txt) - #. ``git commit —amend`` + #. ``git merge cassandra-4.0 -s ours`` + #. ``git format-patch -1 `` (alternative to format-patch and apply is `cherry-pick -n`) + #. ``git apply -3 .patch`` (any issue with CHANGES.txt : fix and `git add CHANGES.txt`) + #. ``ant realclean && ant jar build-test`` (rebuild to make sure code compiles) + #. ``git commit --amend`` (Notice this will squash the trunk applied patch into the forward merge commit) On any branch: - #. ``git push origin cassandra-3.0 cassandra-3.3 trunk —atomic`` + #. ``git push origin cassandra-3.0 cassandra-3.11 cassandra-4.0 trunk --atomic -n`` (dryrun check) + #. ``git push origin cassandra-3.0 cassandra-3.11 cassandra-4.0 trunk --atomic`` + + +Contributions only for release branches +--------------------------------------- + +If the patch is for an older branch, and doesn't impact later branches (such as trunk), we still need to merge up. + +On cassandra-3.0: + #. ``git cherry-pick `` (any problem b/c of CHANGES.txt not merging anymore, fix it in place) + #. ``ant realclean && ant jar build-test`` (rebuild to make sure code compiles) + +On cassandra-3.11: + #. ``git merge cassandra-3.0 -s ours`` + #. ``ant realclean && ant jar build-test`` (rebuild to make sure code compiles) + +On cassandra-4.0: + #. ``git merge cassandra-3.11 -s ours`` + #. ``ant realclean && ant jar build-test`` (rebuild to make sure code compiles) + +On trunk: + #. ``git merge cassandra-4.0 -s ours`` + #. ``ant realclean && ant jar build-test`` (rebuild to make sure code compiles) + +On any branch: + #. ``git push origin cassandra-3.0 cassandra-3.11 cassandra-4.0 trunk --atomic -n`` (dryrun check) + #. ``git push origin cassandra-3.0 cassandra-3.11 cassandra-4.0 trunk --atomic`` + + +Tips +---- + +.. tip:: + + A template for commit messages: + + :: + + + + + patch by ; reviewed by for CASSANDRA-##### + + + Co-authored-by: Name1 + Co-authored-by: Name2 .. tip:: Notes on git flags: ``-3`` flag to am and apply will instruct git to perform a 3-way merge for you. If a conflict is detected, you can either resolve it manually or invoke git mergetool - for both am and apply. - ``—atomic`` flag to git push does the obvious thing: pushes all or nothing. Without the flag, the command is equivalent to running git push once per each branch. This is nifty in case a race condition happens - you won’t push half the branches, blocking other committers’ progress while you are resolving the issue. + ``--atomic`` flag to git push does the obvious thing: pushes all or nothing. Without the flag, the command is equivalent to running git push once per each branch. This is nifty in case a race condition happens - you won’t push half the branches, blocking other committers’ progress while you are resolving the issue. .. tip:: The fastest way to get a patch from someone’s commit in a branch on GH - if you don’t have their repo in remotes - is to append .patch to the commit url, e.g. curl -O https://github.com/apache/cassandra/commit/7374e9b5ab08c1f1e612bf72293ea14c959b0c3c.patch +.. tip:: + + ``git cherry-pick -n `` can be used in place of the ``git format-patch -1 ; git apply -3 .patch`` steps.