This is an automated email from the ASF dual-hosted git repository. mck pushed a commit to branch trunk in repository https://gitbox.apache.org/repos/asf/cassandra-website.git
The following commit(s) were added to refs/heads/trunk by this push: new b1be68c0 Update how_to_commit documentation with lost updates from in-tree repo b1be68c0 is described below commit b1be68c0d9b9e610dd14315c9d42044fe62ec910 Author: Claude Warren, Jr <claude.war...@aiven.io> AuthorDate: Tue Aug 16 07:59:14 2022 +0100 Update how_to_commit documentation with lost updates from in-tree repo Updates were made to the in-tree version of this page that were not included to the rewrite from rst to adoc patch by Claude Warren; reviewed by Mick Semb Wever for CASSANDRA-17599 --- .../ROOT/pages/development/how_to_commit.adoc | 187 ++++++++++++++++----- 1 file changed, 145 insertions(+), 42 deletions(-) diff --git a/site-content/source/modules/ROOT/pages/development/how_to_commit.adoc b/site-content/source/modules/ROOT/pages/development/how_to_commit.adoc index 5a9cf5a7..319a4f0e 100644 --- a/site-content/source/modules/ROOT/pages/development/how_to_commit.adoc +++ b/site-content/source/modules/ROOT/pages/development/how_to_commit.adoc @@ -1,63 +1,156 @@ :page-layout: basic -== How-to Commit += 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. -Here is how committing and merging typically look for merging and -pushing for tickets that follow the convention (if patch-based). -A hypothetical CASSANDRA-12345 ticket used in the example is a cassandra-3.0 -based bug fix that requires different code for cassandra-3.3, and trunk. -Contributor Jackie is supplying a patch for the root branch (12345-3.0.patch), -and patches for the remaining branches (12345-3.3.patch, 12345-trunk.patch). +== 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.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 modify it ourselves, in place) -On cassandra-3.3::: - . `git merge cassandra-3.0 -s ours` - . `git apply -3 12345-3.3.patch` (likely to have an issue with - CHANGES.txt here: modify it ourselves, then `git add CHANGES.txt`) - . `git commit -amend` + . `+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.11::: + . `+git merge cassandra-3.0 -s ours+` + . `+git apply -3 12345-3.11.patch+` (any issue with CHANGES.txt : fix + and [.title-ref]#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 [.title-ref]#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: modify 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 [.title-ref]#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 <sha-of-3.0-commit>` (if we have a problem b/c of - CHANGES.txt not merging anymore, we modify it ourselves, in place) -On cassandra-3.3::: - . `git merge cassandra-3.0 -s ours` - . `git format-patch -1 <sha-of-3.3-commit>` - . `git apply -3 <sha-of-3.3-commit>.patch` (likely to have an issue - with CHANGES.txt here: modify it ourselves, then `git add CHANGES.txt`) - . `git commit -amend` + . `+git cherry-pick <sha-of-3.0-commit>+` (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+` + . `+git format-patch -1 <sha-of-3.11-commit>+` (alternative to + format-patch and apply is [.title-ref]#cherry-pick -n#) + . `+git apply -3 <sha-of-3.11-commit>.patch+` (any issue with + CHANGES.txt : fix and [.title-ref]#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 <sha-of-4.0-commit>+` (alternative to + format-patch and apply is [.title-ref]#cherry-pick -n#) + . `+git apply -3 <sha-of-4.0-commit>.patch+` (any issue with + CHANGES.txt : fix and [.title-ref]#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 <sha-of-trunk-commit>` - . `git apply -3 <sha-of-trunk-commit>.patch` (likely to have an issue - with CHANGES.txt here: modify it ourselves, then `git add CHANGES.txt`) - . `git commit -amend` + . `+git merge cassandra-4.0 -s ours+` + . `+git format-patch -1 <sha-of-trunk-commit>+` (alternative to + format-patch and apply is [.title-ref]#cherry-pick -n#) + . `+git apply -3 <sha-of-trunk-commit>.patch+` (any issue with + CHANGES.txt : fix and [.title-ref]#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 <sha-of-3.0-commit>+` (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] -.Notes on git flags +.Tip ==== -The `-3` flag used with `git am` or `git apply` will instruct git to perform a -3-way merge. -If a conflict is detected, you can either resolve it manually or invoke `git mergetool`. +A template for commit messages: + +[source,none] +---- +<One sentence description, usually Jira title or CHANGES.txt summary> +<Optional lengthier description> + +patch by <Authors>; reviewed by <Reviewers> for CASSANDRA-##### -The `-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 if a race condition occurs - + +Co-authored-by: Name1 <email1> +Co-authored-by: Name2 <email2> +---- +==== + +[TIP] +.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. ==== @@ -65,6 +158,16 @@ while you are resolving the issue. [TIP] .Tip ==== -The fastest way to get a patch from someone’s commit in a branch on github if you don’t have their repo in remote, is to append .patch to the commit url: -`curl -O https://github.com/apache/cassandra/commit/7374e9b5ab08c1f1e612bf72293ea14c959b0c3c.patch` +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] +.Tip +==== +`+git cherry-pick -n <sha-of-X.X-commit>+` can be used in place of the +`+git format-patch -1 <sha-of-X.X-commit> ; git apply -3 <sha-of-X.X-commit>.patch+` +steps. ==== --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@cassandra.apache.org For additional commands, e-mail: commits-h...@cassandra.apache.org