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 966e8979 Improve the how_to_commit page
966e8979 is described below
commit 966e89791f28f1173871c43233d919b86d3ef1e2
Author: mck <[email protected]>
AuthorDate: Wed Dec 17 14:11:26 2025 +0100
Improve the how_to_commit page
Summarise the what and why better.
Lead with the popular git-based approach.
Commit message is not a "tip" but a project standard.
Improve some wordings, remove erroneous/obvious text.
patch by Mick Semb Wever; reviewed by Dmitry Konstantinov, Lukasz Antoniak
for CASSANDRA-21086
---
.../ROOT/pages/development/how_to_commit.adoc | 249 +++++++++++----------
1 file changed, 130 insertions(+), 119 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 e3c2ad1f..a3dccb8a 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
@@ -2,147 +2,161 @@
= 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.
+Commits applicable to multiple versions are atomically pushed forward merges.
-== Patch based Contribution
+The fix lands on the oldest release branch and is then forward-merges it into
each newer branch using an ours merge to record branch lineage and amends that
merge commit to include the branch-appropriate patch.
-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-4.0 based bug fix
-that requires different code for cassandra-4.0, cassandra-4.1, and
-trunk. Contributor Jackie supplied a patch for the root branch
-(12345-4.0.patch), and patches for the remaining branches
-(12345-4.1.patch, 12345-5.0.patch, 12345-trunk.patch).
-
-On cassandra-4.0:::
- . `+git am -3 12345-4.0.patch+` (any problem b/c of CHANGES.txt not
- merging anymore, fix it in place)
- . `+ant realclean && ant jar+` (rebuild to make sure code
- compiles)
- . `+git commit --amend+` (Notice this will squash the 4.0 applied
- patch into the forward merge commit)
-On cassandra-4.1:::
- . `+git merge cassandra-4.0 -s ours --log+`
- . `+git apply -3 12345-4.1.patch+` (any issue with CHANGES.txt : fix
- and [.title-ref]#git add CHANGES.txt#)
- . `+ant realclean && ant jar+` (rebuild to make sure code
- compiles)
- . `+git commit --amend+` (Notice this will squash the 4.1 applied
- patch into the forward merge commit)
-On cassandra-5.0:::
-. `+git merge cassandra-4.1 -s ours --log+`
-. `+git apply -3 12345-5.0.patch+` (any issue with CHANGES.txt : fix
-and [.title-ref]#git add CHANGES.txt#)
-. `+ant realclean && ant jar check+` (rebuild to make sure code
-compiles)
-. `+git commit --amend+` (Notice this will squash the 4.1 applied
-patch into the forward merge commit)
-On trunk:::
- . `+git merge cassandra-5.0 -s ours --log+`
- . `+git apply -3 12345-trunk.patch+` (any issue with CHANGES.txt : fix
- and [.title-ref]#git add CHANGES.txt#)
- . `+ant realclean && ant jar check+` (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-4.0 cassandra-4.1 cassandra-5.0 trunk --atomic
-n+`
- (dryrun check)
- . `+git push origin cassandra-4.0 cassandra-4.1 cassandra-5.0 trunk
--atomic+`
+This keeps a clean, traceable history and a single logical unit of work per
ticket per branch, while preventing unintended diffs from being pulled forward
automatically.
== Git branch based Contribution
-Same scenario, but a branch-based contribution:
-
-On cassandra-4.0:::
- . `+git cherry-pick <sha-of-4.0-commit>+` (any problem b/c of
- CHANGES.txt not merging anymore, fix it in place)
- . `+ant realclean && ant jar+` (rebuild to make sure code
- compiles)
-On cassandra-4.1:::
- . `+git merge cassandra-4.0 -s ours --log+`
- . `+git format-patch -1 <sha-of-4.1-commit>+` (alternative to
- format-patch and apply is [.title-ref]#cherry-pick -n#)
- . `+git apply -3 <sha-of-4.1-commit>.patch+` (any issue with
- CHANGES.txt : fix and [.title-ref]#git add CHANGES.txt#)
- . `+ant realclean && ant jar+` (rebuild to make sure code
- compiles)
- . `+git commit --amend+` (Notice this will squash the 4.1 applied
- patch into the forward merge commit)
-On cassandra-5.0:::
-. `+git merge cassandra-4.1 -s ours --log+`
-. `+git format-patch -1 <sha-of-5.0-commit>+` (alternative to
-format-patch and apply is [.title-ref]#cherry-pick -n#)
-. `+git apply -3 <sha-of-5.0-commit>.patch+` (any issue with
-CHANGES.txt : fix and [.title-ref]#git add CHANGES.txt#)
-. `+ant realclean && ant jar check+` (rebuild to make sure code
-compiles)
-. `+git commit --amend+` (Notice this will squash the 5.0 applied
-patch into the forward merge commit)
-On trunk:::
- . `+git merge cassandra-5.0 -s ours --log+`
- . `+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 check+` (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-4.0 cassandra-4.1 cassandra-5.0 trunk --atomic
-n+`
- (dryrun check)
- . `+git push origin cassandra-4.0 cassandra-4.1 cassandra-5.0 trunk
--atomic+`
+How to commit and merging git-based contributions.
+
+For example, a hypothetical `+CASSANDRA-12345+` ticket is a bug fix that
requires different code for cassandra-4.0, cassandra-4.1, cassandra-5.0 and
trunk. The contributor supplied git fork+branches `+12345/4.0+`, `+12345/4.1+`,
`+12345/5.0+` and `+12345/trunk+`.
+
+
+*On cassandra-4.0*:::
+[source,shell]
+----
+git cherry-pick <sha-of-4.0-commit>
+ant realclean && ant jar # rebuild to make sure code compiles
+----
+*On cassandra-4.1*:::
+[source,shell]
+----
+git merge cassandra-4.0 -s ours --log
+git cherry-pick -n <sha-of-4.1-commit>
+ant realclean && ant jar # rebuild to make sure code compiles
+git commit --amend # this will squash the 4.1 applied patch into the forward
merge commit
+----
+*On cassandra-5.0*:::
+[source,shell]
+----
+git merge cassandra-4.1 -s ours --log
+git cherry-pick -n <sha-of-5.0-commit>
+ant realclean && ant jar check # rebuild to make sure code compiles
+git commit --amend # this will squash the 5.0 applied patch into the forward
merge commit
+----
+*On trunk*:::
+[source,shell]
+----
+git merge cassandra-5.0 -s ours --log
+git cherry-pick -n <sha-of-trunk-commit>
+ant realclean && ant jar check # rebuild to make sure code compiles
+git commit --amend # this will squash the trunk applied patch into the forward
merge commit
+----
+*To Push*:::
+[source,shell]
+----
+git push origin cassandra-4.0 cassandra-4.1 cassandra-5.0 trunk --atomic -n #
dryrun check
+git push origin cassandra-4.0 cassandra-4.1 cassandra-5.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-4.0:::
- . `+git cherry-pick <sha-of-4.0-commit>+` (any problem b/c of
- CHANGES.txt not merging anymore, fix it in place)
- . `+ant realclean && ant jar+` (rebuild to make sure code
- compiles)
-On cassandra-4.1:::
- . `+git merge cassandra-4.0 -s ours --log+`
- . `+ant realclean && ant jar+` (rebuild to make sure code
- compiles)
-On cassandra-5.0:::
-. `+git merge cassandra-4.1 -s ours --log+`
-. `+ant realclean && ant jar check+` (rebuild to make sure code
-compiles)
-On trunk:::
- . `+git merge cassandra-4.1 -s ours --log+`
- . `+ant realclean && ant jar check+` (rebuild to make sure code
- compiles)
-On any branch:::
- . `+git push origin cassandra-4.0 cassandra-4.1 trunk --atomic -n+`
- (dryrun check)
- . `+git push origin cassandra-4.0 cassandra-4.1 trunk --atomic+`
+(such as trunk), we still need to merge up and atomic push.
-== Tips
+*On cassandra-4.0*:::
+[source,shell]
+----
+git cherry-pick <sha-of-4.0-commit>
+ant realclean && ant jar # rebuild to make sure code compiles
+----
+*On cassandra-4.1*:::
+[source,shell]
+----
+git merge cassandra-4.0 -s ours --log
+ant realclean && ant jar # rebuild to make sure code compiles
+----
+*On cassandra-5.0*:::
+[source,shell]
+----
+git merge cassandra-4.1 -s ours --log
+ant realclean && ant jar check # rebuild to make sure code compiles
+----
+*On trunk*:::
+[source,shell]
+----
+git merge cassandra-5.0 -s ours --log
+ant realclean && ant jar check # rebuild to make sure code compiles
+----
+*To Push*:::
+[source,shell]
+----
+git push origin cassandra-4.0 cassandra-4.1 cassandra-5.0 trunk --atomic -n #
dryrun check
+git push origin cassandra-4.0 cassandra-4.1 cassandra-5.0 trunk --atomic
+----
+
+== Patch based Contribution
+
+How to commit and merging patch-based contributions.
+
+For example, a hypothetical `+CASSANDRA-12345+` ticket is a bug fix that
requires different code for cassandra-4.0, cassandra-4.1, cassandra-5.0 and
trunk. The contributor supplied provided the patch for the root branch
`+12345-4.0.patch+`, and patches for the remaining branches
`+12345-4.1.patch+`, `+12345-5.0.patch+` and `+12345-trunk.patch+`.
+
+*On cassandra-4.0*:::
+[source,shell]
+----
+git am -3 12345-4.0.patch
+ant realclean && ant jar # rebuild to make sure code compiles
+git commit --amend # Notice this will squash the 4.0 applied patch into the
forward merge commit
+----
+*On cassandra-4.1*:::
+[source,shell]
+----
+git merge cassandra-4.0 -s ours --log
+git apply -3 12345-4.1.patch
+ant realclean && ant jar # rebuild to make sure code compiles
+git commit --amend # this will squash the 4.1 applied patch into the forward
merge commit
+----
+*On cassandra-5.0*:::
+[source,shell]
+----
+git merge cassandra-4.1 -s ours --log
+git apply -3 12345-5.0.patch
+ant realclean && ant jar check # rebuild to make sure code compiles
+git commit --amend # this will squash the 4.1 applied patch into the forward
merge commit
+----
+*On trunk*:::
+[source,shell]
+----
+git merge cassandra-5.0 -s ours --log
+git apply -3 12345-trunk.patch
+ant realclean && ant jar check # rebuild to make sure code compiles
+git commit --amend # this will squash the trunk applied patch into the forward
merge commit
+----
+*To Push*:::
+[source,shell]
+----
+git push origin cassandra-4.0 cassandra-4.1 cassandra-5.0 trunk --atomic -n #
dryrun check
+git push origin cassandra-4.0 cassandra-4.1 cassandra-5.0 trunk --atomic
+----
+
+== Commit Message
[TIP]
.Tip
====
-A template for commit messages:
+The commit message is to be in the format:
[source,none]
----
<One sentence description, usually Jira title or CHANGES.txt summary>
+
<Optional lengthier description>
-patch by <Authors>; reviewed by <Reviewers> for CASSANDRA-#####
+ patch by <Authors,>; reviewed by <Reviewers,> for CASSANDRA-#####
Co-authored-by: Name1 <email1>
Co-authored-by: Name2 <email2>
----
+
+This format is used by the
https://nightlies.apache.org/cassandra/devbranch/misc/contribulyze/html/[contribulyze
pages].
====
+== Tips
+
[TIP]
.Tip
====
@@ -162,14 +176,11 @@ while you are resolving the issue.
====
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
+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.
+`+git format-patch -1 <sha-of-X.X-commit> ; git apply -3 <format-patch-file>+`
can be used in place of the `+git cherry-pick -n <sha-of-X.X-commit>+` steps.
====
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
