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 <[email protected]>
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: [email protected]
For additional commands, e-mail: [email protected]
